Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/workflows/starter-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,13 @@ jobs:
- run: npm run build
- run: node --test scripts/create-prototype-repo.test.mjs scripts/setup-replica-plugin.test.mjs
working-directory: .

windows-setup:
name: Starter setup (Windows)
runs-on: windows-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
- run: node --test scripts/create-prototype-repo.test.mjs
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Follow the [commit and PR conventions](CONTRIBUTING.md#commits-and-pull-requests

The new Hub has one protected manual workflow for a named non-production Azure installation. It does not publish prototypes or provide a general release service. The starter follows `main` and has no separate release process. Start a new agent session after copying the starter so its local skills are discovered.

For requests to create a prototype repository or set up an existing repository for prototyping, read [prototype repository setup](docs/prototype-repository-setup.md) before acting. It owns target selection, starter installation, the fresh-session handoff, and the path from local preview to optional guidance, a team baseline, or Hub.
For requests to create a prototype repository or set up an existing repository for prototyping, read [prototype repository setup](docs/prototype-repository-setup.md) before acting. It owns target selection, starter installation, the fresh-session handoff, and the path from local preview to optional guidance, a team baseline, or Hub. On native Windows, follow its Git Bash instructions for starter creation.

## Browser validation and Playwright fallback

Expand Down
9 changes: 8 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,14 @@ npm test
npm run build
```

Update starter skills and context templates directly under `starter/.agents/`. Keep authored context in consuming repositories separate from those shared files. For starter-copy, static context library/link and plugin setup checks, run `node --test scripts/create-prototype-repo.test.mjs scripts/setup-replica-plugin.test.mjs` from the repository root. These checks do not verify agent authoring, semantic preservation or activation behavior; use the setup skill's real-host evaluation protocol for that evidence.
Update starter skills and context templates directly under `starter/.agents/`. Keep authored context in consuming repositories separate from those shared files.

Run the setup checks from the repository root:

- On Linux, run `node --test scripts/create-prototype-repo.test.mjs scripts/setup-replica-plugin.test.mjs` to check starter creation, the context library, and plugin setup.
- On native Windows, install the full Git for Windows with Git Bash and run `node --test scripts/create-prototype-repo.test.mjs` for the starter setup checks. The Windows suite does not include plugin setup.

These checks do not verify agent authoring, semantic preservation or activation behavior; use the setup skill's real-host evaluation protocol for that evidence.

Reuse an existing compatible Node.js installation. If it is unavailable on macOS or Linux, get approval before installing [nodenv](https://github.com/nodenv/nodenv), [node-build](https://github.com/nodenv/node-build), or Node.js, or changing shell configuration. The starter installer does not install them.

Expand Down
6 changes: 5 additions & 1 deletion docs/coding-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,11 @@ For TypeScript modules, import the function or component directory without `/ind

## Cross-platform scripts

Scripts used outside Linux must run on Windows, macOS, and Linux without Bash, Git Bash, or WSL. Use Node.js for shared setup and contributor scripts, with native paths and portable subprocess calls. Bash is appropriate for scripts that run only in an explicitly Linux environment, such as a Linux container or CI job; document that requirement.
Choose and document the runtime and supported platforms for each workflow. Share the workflow logic across platforms and test on each platform you claim to support. WSL and Linux containers do not count as native Windows validation.

[Starter creation and installation](prototype-repository-setup.md#2-create-the-independent-starter) use Bash. On native Windows, use Git Bash from the full Git for Windows installation. For Bash scripts, preserve the repository's LF line endings and document any Linux-only tools or features.

When one program launches another, pass arguments separately and use paths understood by the child process. Do not assume the caller's shell makes a program executable on another platform. For example, a Node.js program on Windows cannot launch the `npm.cmd` wrapper directly, even if Node.js was started in Git Bash.

## Tests

Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Hub is being rebuilt. Hosted publishing, sharing, comments, and deployment are n

Download the [GitHub Copilot app](https://github.com/features/ai/github-app), install it, and follow its sign-in instructions.

You also need [Git](https://git-scm.com/), [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), and [Node.js](https://nodejs.org/). Install the Node.js version required by your team's prototyping repository; npm comes with Node.js.
You also need [Git](https://git-scm.com/), [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), and [Node.js](https://nodejs.org/). Install the Node.js version required by your team's prototyping repository; npm comes with Node.js. If you are creating a new starter on native Windows, use [Git for Windows with Git Bash](prototype-repository-setup.md#2-create-the-independent-starter).

The canvas preview workflow supports macOS and Linux. Server discovery requires `lsof` on the machine running the canvas extension; install it with your system's package manager if it is missing. **Start dev server** is supported only on macOS and Linux.

Expand Down
42 changes: 28 additions & 14 deletions docs/prototype-repository-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,41 +21,55 @@ When a reference app is supplied, retain it for the guidance and component work

## 2. Create the independent starter

Without a local Replica checkout, download the installer:
Use Bash and Git for creation. On native Windows, use Git Bash from the full [Git for Windows](https://gitforwindows.org/) installation. In the GitHub Copilot app, choose **This computer** for a native Windows session, not a WSL environment. Git on `PATH` does not mean Git Bash is available. If Git Bash is missing, report that prerequisite instead of switching environments or installing it without approval.

```sh
curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.mjs -o install-starter.mjs
From a local Replica checkout, run this from its root in Bash (Git Bash on Windows). If you clone Replica or select a base branch in Copilot to try an unreleased V2 change, choose the branch that contains that change rather than `main`.

```bash
bash scripts/create-prototype-repo.sh "../my prototype"
```

Read the downloaded script before running it. Use a destination that does not exist and whose parent directory exists:
For the released starter, download the installer from `main`. Use this download only once `main` contains this version of the starter; while developing V2 before that release, use the checkout command. The download needs `curl`, `tar`, and a writable current directory. Use the `curl` and `tar` that come with Git Bash on Windows.

```sh
node --use-env-proxy install-starter.mjs my-prototype
```bash
curl -fLSs https://raw.githubusercontent.com/github/replica/main/scripts/install-starter.sh -o install-starter.sh
```

From a local Replica checkout, use the checked-out script instead:
Read the downloaded script before running it:

```bash
bash ./install-starter.sh "./my prototype"
```

When releasing V2 to `main`, run these download and install commands with a fresh destination on native Windows. Verify that the archive provides the V2 starter and that the new repository has no commit or remote.

If the agent is in PowerShell or another shell that cannot run the Bash script, locate `bin\bash.exe` under the actual Git for Windows installation and invoke that executable directly. Do not use a bare `bash` or `bash.exe` from `PATH`; it may point to a different shell or WSL. For example, in PowerShell:

```sh
node scripts/create-prototype-repo.mjs ../my-prototype
```powershell
$gitBash = 'C:\Program Files\Git\bin\bash.exe' # Use your verified Git for Windows path.
if (-not (Test-Path -LiteralPath $gitBash -PathType Leaf)) {
throw 'Locate Git for Windows bin\bash.exe, or install Git for Windows with Git Bash.'
}
& $gitBash 'scripts/create-prototype-repo.sh' '..\my prototype'
```

Both paths create an independent, uncommitted Git repository with no remote. They copy the starter without Replica's source history, require no GitHub credentials, and publish nothing. The installer does not install Node.js or app dependencies.
Keep the script path and destination as separate arguments. For the reviewed download, pass `'./install-starter.sh'` and `'.\my prototype'` instead. If the script starts and returns an error, report the error. Do not retry it in another shell.

Use a Node.js version supported by the starter and Git. The `--use-env-proxy` option lets Node use configured `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` settings. Downloaded installation also needs tar and a writable current directory for temporary downloads. Creation runs without Bash on Windows, macOS and Linux. This does not change the [Linux requirements for local Hub Builds](../hub/docs/development.md#build-local-prototype-repositories).
Choose a destination that does not exist and whose parent directory exists. Both commands create an independent, uncommitted Git repository with no remote. They copy the starter without Replica's source history, require no GitHub credentials, and publish nothing. Creation does not require or install Node.js or app dependencies. This does not change the [Linux requirements for local Hub Builds](../hub/docs/development.md#build-local-prototype-repositories).

Before asking the user to accept the copied repository's Copilot app configuration, review `.github/github-app.yml` and the startup details in the copied `README.md`. Explain that session startup can install Copilot CLI globally when missing, install or enable the Replica plugin, and will run `npm ci`.

Add the new directory to the Copilot app using **Projects → + → Local folder or repository**, then start a fresh session there. The session in the Replica checkout cannot discover the copied local skills.
Open the new directory as a local folder in the Copilot app, then start a fresh session in its current checkout. Do not clone again or create a worktree from the uncommitted starter. The session in the Replica checkout cannot discover the copied local skills.

Before ending the originating session, provide a paste-ready kickoff message headed **Prompt 1: Continue prototype repository setup**. Tell the user to paste it into the fresh session; a new session does not inherit the previous conversation. Include the user's goal, repository path, supplied references, requested milestone, settled decisions and approvals, completed actions, blockers, and next step.
Before ending the originating session, provide a paste-ready kickoff message headed **Prompt 1: Continue prototype repository setup**. Tell the user to paste it into the fresh session; a new session does not inherit the previous conversation. Include the user's goal, repository path, supplied references, requested milestone, settled decisions and approvals, completed actions, blockers, and next step. For Windows, include which shell ran creation and whether Copilot Startup was checked.

The kickoff must tell the new session to follow the copied repository's `AGENTS.md` and resume this guide at step 3. Include the [absolute guide URL](https://github.com/github/replica/blob/main/docs/prototype-repository-setup.md#3-verify-the-existing-app-locally), since this guide is not copied into the starter. If that version is not yet available at the URL, include steps 3 through 5 inline instead. The new session reuses settled answers and checks which actions and approvals remain applicable.

## 3. Verify the existing app locally

Check `node --version` against `engines.node` in the copied `package.json`. Reuse a compatible installed runtime. On macOS or Linux, obtain approval before installing Node.js, nodenv, or node-build, or changing shell configuration.

The fresh session does not receive the setup output, so ask the user to inspect it and report any failures before repeating setup. Dependency installation success does not prove that the current session loaded the canvas.
The fresh session does not receive the setup output, so ask the user to inspect it and report any failures before repeating setup. Copilot Startup uses the app's own command runner. On native Windows, successful creation or a terminal `npm ci` does not verify Startup. Dependency installation success does not prove that the current session loaded the canvas.

Follow the copied README's **Connect the Replica canvas** and **Canvas preflight** sections for plugin activation and recovery. Complete that preflight before starting a preview. Use its **Run it** commands, reuse an existing responsive server when appropriate, and open the actual printed URL. Verify that the included app renders; a successful dependency install or HTTP response alone is not a rendered check.

Expand Down
2 changes: 2 additions & 0 deletions docs/testing-and-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@ Maintainers must update branch rules when required checks change. Editing a work

Hub, Starter, build-action, and Learning CI test both Node.js majors supported by each project's `engines.node`. The workflow matrices define the versions and distinguish their check names. A failure on one version does not cancel checks on the other. npm installation enforces dependency engines. The workflow checker verifies that the manifests, lockfiles, and matrices agree.

Starter CI also runs the creator and installer tests on native Windows with Git for Windows and one supported Node.js version. This job does not duplicate the Linux Starter build or test Copilot Startup or canvas availability.

Scripts CI and dependency-age checks use the Node.js version specified in their workflows. The build-action suite tests JavaScript and browser capture on both supported majors. Its composite-action smoke test uses separate dist and screenshot jobs on the action's pinned runtime, outside the Node matrix to avoid duplicate artifact uploads. The screenshot job depends on the dist job because it consumes that job's artifact; this functional dependency is not an aggregate result gate.

## Update dependencies
Expand Down
2 changes: 2 additions & 0 deletions hub/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ Open <http://127.0.0.1:5173/repositories/2001> for the mock frontend; it needs n

After installing Hub dependencies, use the [devcontainer](docs/development.md#devcontainer) for the real API or prepare local PostgreSQL and configuration. Copy `.env.example` only for first-time setup; preserve an existing `.env` and never commit credentials.

On native Windows, [local example seeding](docs/development.md#start-with-the-real-api) requires Git for Windows with Git Bash. This is separate from the Linux-only Local Build workflow.

```sh
docker compose -f .devcontainer/compose.yaml up -d db
[ -e .env ] || [ -L .env ] || cp -n .env.example .env
Expand Down
4 changes: 2 additions & 2 deletions hub/docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ Local-mode startup prepares the absolute `LOCAL_PROTOTYPE_ROOT`, defaulting to t

When the prototype root is empty, the first start creates `minimal/` from the canonical [Replica Starter](../../starter/), installs its locked dependencies, commits `main`, and creates the committed `prototype/example` branch with a scaffolded example route. The commits use fixed example authorship and timestamps so the same starter revision produces the same repository history. Preparation also installs the shared [Build action](../../actions/build/) runtime dependencies from its lockfile and its pinned Chromium browser. It skips the npm install when the required dependencies are already present; Playwright's browser installation is idempotent.

Hub uses the same [Bash creator](../../scripts/create-prototype-repo.sh) as standalone starter setup. On native Windows, install Git for Windows with Git Bash and put its `git.exe` on `PATH`. Hub finds `bin\bash.exe` in that installation; it does not depend on the terminal's shell. Dependency installation still runs npm's JavaScript entrypoint through Node.js, using `npm_execpath` when supplied or the npm bundled beside Node.js.

Later starts always prepare the shared Build action dependencies, but they do not add, replace, switch, or commit anything in a nonempty prototype root. This includes the seeded repository after a developer edits it. To prepare without keeping the API running, use:

```sh
Expand Down Expand Up @@ -114,8 +116,6 @@ The filesystem provider requires the Linux protections described in [Artifact st
npm run local:builds
```

Starter preparation invokes the [Node.js creator](../../scripts/create-prototype-repo.mjs), not Bash. On Windows, dependency installation runs npm's JavaScript entrypoint through Node.js, using `npm_execpath` when supplied or the npm bundled beside Node.js. These setup fixes do not remove the Linux filesystem requirement or Docker isolation for local Builds.

Alternatively, after `npm run setup`, enqueue the same scan and run the local on-demand worker:

```sh
Expand Down
Loading
Loading