@decohere/create 0.0.1-dev.20 → 0.0.1-dev.20261105.110

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 Typesmiths
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# @decohere/create
+
+Scaffold a new Decohere project — built with Forge, served with Flux.
+
+Docker is required on the host. `@decohere/create` only pulls `ghcr.io/typesmiths/decohere/create` and runs `@decohere/scaffold` inside it (including the Auth0 CLI). It does not install the scaffolder libraries on the host.
+
+## Usage
+
+`npm create` already says “create”, so the first token is the kind (`webapi`), not `create` again. The launcher forwards `decohere create webapi …` into the builder image.
+
+This run prompts for database, auth, Postman, and whether to install:
+
+```bash
+npm create @decohere@dev webapi -d my-app
+# or
+npx @decohere/create@dev webapi -d my-app
+# or, once `@decohere/cli` is installed:
+decohere create webapi -d my-app
+```
+
+To skip prompts, pass every answer up front (`-y` means “install deps, don’t ask”):
+
+```bash
+npm create @decohere@dev -- webapi -d my-app --database postgres/typeorm --auth none --postman local -y
+```
+
+Target directory is `webapi`'s optional argument or `-d` (default `.`). `npm create` treats `-d` as its own loglevel flag and forwards `my-app` as a positional — that form is supported. Extra create flags still need `--` after `npm create`.
+
+The first token after the package must be a command (`webapi`); a bare directory name is an unknown command.
+
+The scaffolded Dev Container asks **y/N** (TTY only) before npm auth and optional codebase RAG MCP (semantic search). Decline or run without a TTY to skip. Credentials are written under the project `.cursor/` directory (gitignored).
+
+## Commands
+
+### `webapi`
+
+Scaffolds a full web API using `@decohere/http` (HTTP), `@decohere/crucible` (DI), `@decohere/config` (configuration) and Scribe (logging), plus a Dev Container workspace.
+
+```bash
+npx @decohere/create webapi -d my-app
+npx @decohere/create webapi -d my-app --name billing
+npx @decohere/create webapi -d my-app --name api --name billing
+```
+
+Generated structure (default `--name api`):
+
+```
+my-app/
+  package.json          # build / start / start:<name> / dev
+  .github/
+    actions/setup-node-pnpm/
+    workflows/
+      ci.yml            # lint ∥ test (+ build and package on default branch)
+      publish.yml       # forge publish (skips private); no docker push by default
+  tsconfig.json
+  biome.json
+  pnpm-workspace.yaml   # tells pnpm not to run the SWC and esbuild install scripts
+  .env
+  config/
+    config.yaml
+    config.dev.yaml
+  .devcontainer/
+  projects/
+    api/                # or projects/<name> when --name is set
+      package.json      # private: true (app, not an npm package)
+      Dockerfile        # copies .package/ (written by `forge package`)
+      .dockerignore
+      src/
+        main.ts
+        sample.config.ts
+        sample.service.ts
+        controllers/
+          hello.controller.ts
+```
+
+Every API gets its own `projects/<name>/Dockerfile`; that folder is the Docker build context. The Dockerfile copies `.package/`, which `forge package` writes (see below).
+
+The app Dev Container is a thin `FROM ghcr.io/typesmiths/decohere/devcontainer:<version>` (pinned to the scaffolder version). Shared layers (bash history, pnpm, `gh`, js-debug bootloader fix) update via `docker pull` / Dev Container rebuild — Compose mounts and lifecycle scripts stay in the app repo. Rebuild with pull after upgrading `@decohere/create`.
+
+#### Scripts
+
+| Script | Command | When |
+|---|---|---|
+| `build` | `forge build --configuration release` | CI, Nixpacks |
+| `package` / `package:<name>` | release build, then `forge package` (all APIs, or that one) | Before `docker build` |
+| `start` | `node dist/release/projects/<first>/es6/src/main.js` | Production default API (`pnpm start`) |
+| `start:<name>` | same path for that API | Deploy that API (`pnpm run start:billing`) |
+| `dev` | `flux serve --env-file-if-exists .env` (plus `--project @<app>/<first>` when named) | Local HMR for the first API; loads `.env` if present |
+| `dev:<name>` | `PORT=<3000+n> flux serve --env-file-if-exists .env --project @<app>/<name>` | Local HMR for that API |
+| `lint:check` / `typecheck` / `test` | biome / forge typecheck / vitest | CI |
+
+#### Multiple APIs / add later
+
+```bash
+decohere add api billing
+# empty machine / npm create still maps `webapi add`:
+npx @decohere/create webapi add billing -d my-app
+```
+
+Adds `projects/billing`, `start:billing` / `package:billing` / `dev:billing`, and `projects/billing/Dockerfile`. Does not rewrite the first API or workspace files like `biome.json`.
+
+Each API is a separate deploy: package it (`pnpm run package:billing`) and build the image from its folder (`docker build projects/billing`), or set the start command to `pnpm run start:billing`. Workspace `config/` is shared; each API still has its own named datasource and `{PREFIX}_DB_*` env (host/port default to the Compose Postgres).
+
+### `auth0`
+
+The Auth0 CLI lives in the create image. Host tokens are stored in `~/.config/auth0` (always bind-mounted). Use this after a project exists, when a token expires, or when the Postman SPA needs to be created/updated.
+
+```bash
+# Device/URL login — open the printed URL in your browser
+npx @decohere/create auth0 login
+
+# Update the Auth0 API + Postman SPA for this workspace (run from the project, or pass -d)
+npx @decohere/create auth0 configure
+npx @decohere/create auth0 configure -d my-app
+
+# Same commands once `@decohere/cli` is installed:
+decohere auth0 login
+decohere auth0 configure
+```
+
+`configure` does **not** rewrite application source. It scans `projects/*/src` for `@Authorize("action", "Subject")`, adds those permissions to the Auth0 API (keeping any already on the API), assigns them to `AUTH0_ADMIN_USER_SUB` when set, and updates Postman token `scope`.
+
+#### Keep Auth0 in sync with controllers
+
+`@Authorize("read", "Invoice")` becomes Auth0 API permission `read:Invoice`. After adding a controller:
+
+```bash
+npx @decohere/create auth0 configure
+```
+
+Then in Postman, Authorization → Get New Access Token so the token includes the new permissions.
+
+#### Deploy (Railway / Fly / Nixpacks)
+
+The production image does not install or build anything: it copies `.package/`, the folder `forge package` writes inside the API project (the API's compiled code, the workspace libraries it imports, and a plain `node_modules` of the third-party packages it uses, with no symlinks). Run `pnpm run package` (or `package:<name>`) first, then `docker build projects/<name>`.
+
+1. **CI builds the image (preferred):** run `pnpm run package`, then `pnpm exec forge docker --configuration release --push`. Private `@decohere/*` packages need npm auth only in that package step, never in the image build.
+2. **Hosts that build from a git clone** (Railway, Fly) do not have `.package/`, because it is build output. Build the image in CI and deploy it, or run the package step before `docker build`.
+3. **Nixpacks (no Dockerfile):** conventional `build` / `start` scripts — install → build → start.
+
+Commit `pnpm-lock.yaml` after the first install.
+
+**Registry push (optional):** CI does not run `forge docker --push` by default. For Cloud Run / K8s, add `pnpm run package` and that step to `publish.yml` after configuring GHCR.
+
+**Conventions:** `"private": true` → skip npm publish; presence of a Dockerfile → dockerizable; non-private packages under `projects/` → `forge publish`.
+
+#### Database (`--database`)
+
+| Value | Effect |
+|---|---|
+| `none` | No database |
+| `postgres/typeorm` | One Compose Postgres **instance**; each API owns a named database + `{PREFIX}_DB_*` env |
+
+```bash
+npx @decohere/create webapi -d my-app --database postgres/typeorm
+npx @decohere/create webapi -d my-app --name api --name billing --database postgres/typeorm
+```
+
+`config.yaml` lists one datasource per API (`name: billing` → `withTypeOrm({ name: "billing" })`). Locally they share host `postgres` port `5432`. Point `BILLING_DB_HOST` / `BILLING_DB_PORT` at another server to split later. `webapi add billing --database postgres/typeorm` appends a datasource; TypeORM bootstrap `CREATE DATABASE`s it on first run.
+
+#### Health probes
+
+Scaffolded APIs call `.withHealth()` so these routes are available **without auth**:
+
+| Route | Purpose | Status |
+|---|---|---|
+| `GET /health` | Liveness — process is up | Always `200` `{ "status": "ok" }` |
+| `GET /ready` | Readiness — dependencies OK | `200` when checks pass; `503` when a check fails |
+
+With `--database postgres/typeorm`, readiness runs `SELECT 1` against each TypeORM datasource. Use `/ready` for load balancers and orchestrators.
+
+#### Auth (`--auth`)
+
+| Value | Effect |
+|---|---|
+| `none` | No auth |
+| `auth0` | Auth0 JWT protection; with Postgres also scaffolds a local User profile |
+
+```bash
+npx @decohere/create webapi -d my-app --auth auth0
+```
+
+With Auth0 + Postgres, customize authorization in `projects/<api>/src/auth/ability.factory.ts`:
+override `defineAbilitiesFor` for product CASL rules, and `mapPrincipal` for IdP claim mapping
+(including the `AUTH0_ADMIN_USER_SUB` admin bootstrap). `@decohere/http`'s default already maps
+`admin` → `manage`/`all` and `action:Subject` scopes.
+
+#### Postman (`--postman`)
+
+| Value | Effect |
+|---|---|
+| `none` | Skip Postman |
+| `local` | Local View collection + environment under `postman/` |
+| `api` | Create collection/environment in a Postman cloud workspace |
+
+```bash
+npx @decohere/create webapi -d my-app --postman local
+```
+
+## Options
+
+| Option | Scope | Description |
+|---|---|---|
+| `[directory]` / `-d <directory>` | `webapi` / global | Target directory (positional wins; default `.`) |
+| `--name <slug>` | `webapi` | API directory under `projects/` (repeatable; default `api`) |
+| `add api <name>` | `decohere add api` / `npx @decohere/create webapi add` | Add an API to an existing Decohere workspace |
+| `auth0 login` | `decohere auth0` / `npx @decohere/create auth0` | Device/URL login; persist tokens in `~/.config/auth0` |
+| `auth0 configure` | `decohere auth0` / `npx @decohere/create auth0` | Update Auth0 API + Postman SPA for an existing workspace |
+| `--database <provider>` | `webapi` / `add` | `none` \| `postgres/typeorm` |
+| `--auth <provider>` | `webapi` / `add` | `none` \| `auth0` |
+| `--postman <provider>` | `webapi` / `add` | `none` \| `local` \| `api` |
+| `-y, --yes` | `webapi` / `add` | Install dependencies without prompting |
+| `--install <mode>` | `webapi` / `add` | `ask` (default) \| `yes` \| `no` |
+
+## Next steps
+
+After scaffolding:
+
+```bash
+cd my-app
+code .          # open in VS Code / Dev Container
+pnpm build      # forge release build
+pnpm start      # run compiled API (production)
+pnpm dev        # Flux HMR (development)
+```
+
+## Troubleshooting
+
+### GHCR pull fails with `403 Forbidden`
+
+If scaffolding fails with an error like:
+
+```text
+failed to resolve reference "ghcr.io/typesmiths/decohere/create:<version>": ... 403 Forbidden
+```
+
+your GitHub token likely does not include the `read:packages` scope.
+
+1. Create or use a token with at least `read:packages`.
+2. If the package is private/internal, also include `repo`.
+3. Re-login to GHCR and retry.
+
+```bash
+export GH_TOKEN=YOUR_PAT_WITH_READ_PACKAGES
+echo "$GH_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
+docker pull ghcr.io/typesmiths/decohere/create:<version>
+```
+
+You can verify scopes with:
+
+```bash
+gh auth status -t
+```
+
+If you still get `403` after adding `read:packages`, ask an org admin to grant your user/team access to the `typesmiths/decohere/create` package.

package/es6/src/cli.js

@@ -1,36 +1,3 @@
 #!/usr/bin/env node
-import { Command } from "commander";
 import { runInBuilder } from "./runner.js";
-import { scaffoldApi } from "./webapi/create-api.js";
-const program = new Command();
-program.name("decohere").description("Scaffold a new Decohere project").option("-d <directory>", "Target directory (default: current directory)", ".");
-program.command("webapi").action(async (_name, cmd)=>{
-    const opts = cmd.optsWithGlobals();
-    if (process.env.DECOHERE_BUILDER !== "1") {
-        runInBuilder(opts);
-        return;
-    }
-    await scaffoldApi(opts);
-});
-// .option("-y, --yes", "Skip confirmation prompts")
-// .option("-t, --template <template>", "Project template: api (default) or cli")
-// .option("-d, --database <provider>", "Database provider to include (api only): typeorm")
-// .option("-i, --idp <provider>", "Identity provider to configure (api only): auth0")
-// .option("-p, --postman", "Configure a Postman workspace, collection, and environment")
-// .action(
-// 	async (
-// 		directory: string,
-// 		opts: {
-// 			yes?: boolean;
-// 			template?: "api" | "cli";
-// 			database?: "typeorm";
-// 			idp?: "auth0";
-// 			postman?: boolean;
-// 		},
-// 	) => {
-// 		await scaffold(resolve(directory), opts);
-// 	},
-// );
-program.parse();
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NyZWF0ZS9zcmMvY2xpLnRzIl0sInNvdXJjZXNDb250ZW50IjpbIiMhL3Vzci9iaW4vZW52IG5vZGVcbmltcG9ydCB7IENvbW1hbmQgfSBmcm9tIFwiY29tbWFuZGVyXCI7XG5pbXBvcnQgeyBydW5JbkJ1aWxkZXIgfSBmcm9tIFwiLi9ydW5uZXIuanNcIjtcbmltcG9ydCB7IHNjYWZmb2xkQXBpIH0gZnJvbSBcIi4vd2ViYXBpL2NyZWF0ZS1hcGkuanNcIjtcblxuY29uc3QgcHJvZ3JhbSA9IG5ldyBDb21tYW5kKCk7XG5cbnByb2dyYW1cblx0Lm5hbWUoXCJkZWNvaGVyZVwiKVxuXHQuZGVzY3JpcHRpb24oXCJTY2FmZm9sZCBhIG5ldyBEZWNvaGVyZSBwcm9qZWN0XCIpXG5cdC5vcHRpb24oXCItZCA8ZGlyZWN0b3J5PlwiLCBcIlRhcmdldCBkaXJlY3RvcnkgKGRlZmF1bHQ6IGN1cnJlbnQgZGlyZWN0b3J5KVwiLCBcIi5cIik7XG5cbnByb2dyYW0uY29tbWFuZChcIndlYmFwaVwiKS5hY3Rpb24oYXN5bmMgKF9uYW1lLCBjbWQ6IENvbW1hbmQpID0+IHtcblx0Y29uc3Qgb3B0cyA9IGNtZC5vcHRzV2l0aEdsb2JhbHMoKTtcblx0aWYgKHByb2Nlc3MuZW52LkRFQ09IRVJFX0JVSUxERVIgIT09IFwiMVwiKSB7XG5cdFx0cnVuSW5CdWlsZGVyKG9wdHMpO1xuXHRcdHJldHVybjtcblx0fVxuXHRhd2FpdCBzY2FmZm9sZEFwaShvcHRzKTtcbn0pO1xuXG4vLyAub3B0aW9uKFwiLXksIC0teWVzXCIsIFwiU2tpcCBjb25maXJtYXRpb24gcHJvbXB0c1wiKVxuLy8gLm9wdGlvbihcIi10LCAtLXRlbXBsYXRlIDx0ZW1wbGF0ZT5cIiwgXCJQcm9qZWN0IHRlbXBsYXRlOiBhcGkgKGRlZmF1bHQpIG9yIGNsaVwiKVxuLy8gLm9wdGlvbihcIi1kLCAtLWRhdGFiYXNlIDxwcm92aWRlcj5cIiwgXCJEYXRhYmFzZSBwcm92aWRlciB0byBpbmNsdWRlIChhcGkgb25seSk6IHR5cGVvcm1cIilcbi8vIC5vcHRpb24oXCItaSwgLS1pZHAgPHByb3ZpZGVyPlwiLCBcIklkZW50aXR5IHByb3ZpZGVyIHRvIGNvbmZpZ3VyZSAoYXBpIG9ubHkpOiBhdXRoMFwiKVxuLy8gLm9wdGlvbihcIi1wLCAtLXBvc3RtYW5cIiwgXCJDb25maWd1cmUgYSBQb3N0bWFuIHdvcmtzcGFjZSwgY29sbGVjdGlvbiwgYW5kIGVudmlyb25tZW50XCIpXG4vLyAuYWN0aW9uKFxuLy8gXHRhc3luYyAoXG4vLyBcdFx0ZGlyZWN0b3J5OiBzdHJpbmcsXG4vLyBcdFx0b3B0czoge1xuLy8gXHRcdFx0eWVzPzogYm9vbGVhbjtcbi8vIFx0XHRcdHRlbXBsYXRlPzogXCJhcGlcIiB8IFwiY2xpXCI7XG4vLyBcdFx0XHRkYXRhYmFzZT86IFwidHlwZW9ybVwiO1xuLy8gXHRcdFx0aWRwPzogXCJhdXRoMFwiO1xuLy8gXHRcdFx0cG9zdG1hbj86IGJvb2xlYW47XG4vLyBcdFx0fSxcbi8vIFx0KSA9PiB7XG4vLyBcdFx0YXdhaXQgc2NhZmZvbGQocmVzb2x2ZShkaXJlY3RvcnkpLCBvcHRzKTtcbi8vIFx0fSxcbi8vICk7XG5cbnByb2dyYW0ucGFyc2UoKTtcbiJdLCJuYW1lcyI6WyJDb21tYW5kIiwicnVuSW5CdWlsZGVyIiwic2NhZmZvbGRBcGkiLCJwcm9ncmFtIiwibmFtZSIsImRlc2NyaXB0aW9uIiwib3B0aW9uIiwiY29tbWFuZCIsImFjdGlvbiIsIl9uYW1lIiwiY21kIiwib3B0cyIsIm9wdHNXaXRoR2xvYmFscyIsInByb2Nlc3MiLCJlbnYiLCJERUNPSEVSRV9CVUlMREVSIiwicGFyc2UiXSwibWFwcGluZ3MiOiI7QUFDQSxTQUFTQSxPQUFPLFFBQVEsWUFBWTtBQUNwQyxTQUFTQyxZQUFZLFFBQVEsY0FBYztBQUMzQyxTQUFTQyxXQUFXLFFBQVEseUJBQXlCO0FBRXJELE1BQU1DLFVBQVUsSUFBSUg7QUFFcEJHLFFBQ0VDLElBQUksQ0FBQyxZQUNMQyxXQUFXLENBQUMsbUNBQ1pDLE1BQU0sQ0FBQyxrQkFBa0IsaURBQWlEO0FBRTVFSCxRQUFRSSxPQUFPLENBQUMsVUFBVUMsTUFBTSxDQUFDLE9BQU9DLE9BQU9DO0lBQzlDLE1BQU1DLE9BQU9ELElBQUlFLGVBQWU7SUFDaEMsSUFBSUMsUUFBUUMsR0FBRyxDQUFDQyxnQkFBZ0IsS0FBSyxLQUFLO1FBQ3pDZCxhQUFhVTtRQUNiO0lBQ0Q7SUFDQSxNQUFNVCxZQUFZUztBQUNuQjtBQUVBLG9EQUFvRDtBQUNwRCxpRkFBaUY7QUFDakYsMkZBQTJGO0FBQzNGLHNGQUFzRjtBQUN0Rix5RkFBeUY7QUFDekYsV0FBVztBQUNYLFdBQVc7QUFDWCx1QkFBdUI7QUFDdkIsWUFBWTtBQUNaLG9CQUFvQjtBQUNwQiwrQkFBK0I7QUFDL0IsMkJBQTJCO0FBQzNCLG9CQUFvQjtBQUNwQix3QkFBd0I7QUFDeEIsT0FBTztBQUNQLFVBQVU7QUFDViw4Q0FBOEM7QUFDOUMsTUFBTTtBQUNOLEtBQUs7QUFFTFIsUUFBUWEsS0FBSyJ9
+runInBuilder(process.argv.slice(2));

package/es6/src/index.js

@@ -0,0 +1,2 @@
+export { containerArgvFromHost, resolveLaunch, toProductArgv } from "./resolve-launch.js";
+export { runInBuilder } from "./runner.js";

package/es6/src/resolve-launch.js

@@ -0,0 +1,87 @@
+import { basename, resolve } from "node:path";
+const HOST_FLAGS_WITH_VALUE = new Set([
+    "--config-file",
+    "--log-level"
+]);
+/**
+ * Map host / npm-create argv onto the product CLI (`create webapi` / `add api`).
+ * `npm create @decohere webapi` already says “create”, so we prepend `create`
+ * rather than making users type `create create webapi`.
+ */ export function toProductArgv(tokens) {
+    if (tokens[0] === "webapi" && tokens[1] === "add") {
+        return [
+            "add",
+            "api",
+            ...tokens.slice(2)
+        ];
+    }
+    if (tokens[0] === "webapi") {
+        return [
+            "create",
+            "webapi",
+            ...tokens.slice(1)
+        ];
+    }
+    return tokens;
+}
+export function containerArgvFromHost(argv) {
+    const user = argv[0]?.includes("node") || argv[0]?.endsWith("node") ? argv.slice(2) : argv;
+    const stripped = [];
+    for(let i = 0; i < user.length; i++){
+        const arg = user[i];
+        if (arg != null && HOST_FLAGS_WITH_VALUE.has(arg)) {
+            i++;
+            continue;
+        }
+        if (arg != null) stripped.push(arg);
+    }
+    return toProductArgv(stripped);
+}
+/**
+ * Host argv → directory to mount and argv for the in-image `decohere` entrypoint.
+ * Positional `webapi my-app` / `create webapi my-app` wins over `-d` (npm treats `-d`
+ * as its own loglevel).
+ */ export function resolveLaunch(argv, cwd = process.cwd()) {
+    if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "--version")) {
+        return {
+            targetDir: cwd,
+            containerArgv: argv,
+            projectName: basename(cwd),
+            kind: "scaffold"
+        };
+    }
+    let directoryFlag;
+    const withoutD = [];
+    for(let i = 0; i < argv.length; i++){
+        const arg = argv[i];
+        if (arg === "-d") {
+            directoryFlag = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (arg != null) withoutD.push(arg);
+    }
+    const product = toProductArgv(withoutD);
+    const isAdd = product[0] === "add";
+    let positional;
+    let withoutPositional = product;
+    if (!isAdd && product[0] === "create" && product[1] === "webapi" && product[2] != null && !product[2].startsWith("-")) {
+        positional = product[2];
+        withoutPositional = [
+            product[0],
+            product[1],
+            ...product.slice(3)
+        ];
+    }
+    const targetDir = resolve(cwd, positional?.trim() || directoryFlag?.trim() || ".");
+    return {
+        targetDir,
+        containerArgv: [
+            ...withoutPositional,
+            "-d",
+            "."
+        ],
+        projectName: basename(targetDir),
+        kind: product[0] === "auth0" ? "auth0" : "scaffold"
+    };
+}

package/es6/src/runner.js

@@ -1,23 +1,23 @@
 import { execFileSync, spawnSync } from "node:child_process";
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { CREATE_VERSION } from "./version.js";
-const BUILDER_IMAGE = `ghcr.io/decohere/scaffold:${CREATE_VERSION}`;
+import { resolveLaunch } from "./resolve-launch.js";
+import { CREATE_IMAGE_REPOSITORY, CREATE_VERSION } from "./version.js";
+const BUILDER_IMAGE = `${CREATE_IMAGE_REPOSITORY}:${CREATE_VERSION}`;
 /**
- * Run the scaffold inside a pre-built Docker builder image.
- *
- * Called when `DECOHERE_BUILDER` is not set — i.e. the CLI is running on the
- * host, outside the container. Mounts the target directory as `/workspace` so
- * the scaffolded files are written back to the host filesystem.
- *
- * If `~/.config/auth0` exists on the host the directory is also mounted so
- * the auth0 CLI inside the container can reuse existing credentials silently.
- */ export function runInBuilder(opts) {
-    const targetDir = resolve(opts.d ?? ".");
+ * Pull/run the Decohere scaffolder image. Host `@decohere/create` does not load
+ * the `@decohere/scaffold` dependency tree — that lives in the image only.
+ */ export function runInBuilder(argv) {
+    const { targetDir, containerArgv, projectName, kind } = resolveLaunch(argv);
     mkdirSync(targetDir, {
         recursive: true
     });
-    // Ensure Docker is available.
+    if (kind === "scaffold") {
+        mkdirSync(resolve(targetDir, ".devcontainer", "npm-auth"), {
+            recursive: true
+        });
+    }
     try {
         execFileSync("docker", [
             "info"
@@ -28,28 +28,71 @@ const BUILDER_IMAGE = `ghcr.io/decohere/scaffold:${CREATE_VERSION}`;
         console.error("\n  Docker is required to scaffold a Decohere project.\n" + "  Install Docker Desktop: https://www.docker.com/products/docker-desktop\n");
         process.exit(1);
     }
+    const hostUid = process.getuid?.();
+    const hostGid = process.getgid?.() ?? hostUid;
+    const runAsHostUser = hostUid != null && hostGid != null;
+    const npmCacheDir = resolve(homedir(), ".cache/decohere-create/npm");
+    mkdirSync(npmCacheDir, {
+        recursive: true
+    });
+    const builderHome = "/tmp/decohere-create-home";
     const volumes = [
         "-v",
-        `${targetDir}:/workspace`
+        `${targetDir}:/workspace`,
+        "-v",
+        `${npmCacheDir}:/npm-cache`
+    ];
+    const envArgs = [
+        "-e",
+        "DECOHERE_BUILDER=1",
+        "-e",
+        `DECOHERE_PROJECT_NAME=${projectName}`,
+        "-e",
+        "NPM_CONFIG_CACHE=/npm-cache",
+        "-e",
+        "NPM_CONFIG_PREFER_OFFLINE=true",
+        "-e",
+        `HOME=${builderHome}`
+    ];
+    const npmrcPath = resolve(homedir(), ".npmrc");
+    if (existsSync(npmrcPath)) {
+        volumes.push("-v", `${npmrcPath}:/tmp/host-npmrc:ro`);
+        envArgs.push("-e", "NPM_CONFIG_USERCONFIG=/tmp/host-npmrc");
+    }
+    const auth0ConfigDir = resolve(homedir(), ".config/auth0");
+    mkdirSync(auth0ConfigDir, {
+        recursive: true
+    });
+    volumes.push("-v", `${auth0ConfigDir}:${builderHome}/.config/auth0`);
+    const userArgs = [];
+    if (runAsHostUser) {
+        userArgs.push("--user", `${hostUid}:${hostGid}`);
+    } else if (hostUid != null) {
+        envArgs.push("-e", `HOST_UID=${hostUid}`);
+        if (hostGid != null) envArgs.push("-e", `HOST_GID=${hostGid}`);
+    }
+    console.log(kind === "auth0" ? "  Running Auth0 CLI in the scaffolder image...\n" : "  Running scaffolding in a sandboxed container...\n");
+    const ttyFlags = process.stdin.isTTY ? [
+        "-it"
+    ] : [
+        "-i"
     ];
-    console.log("  Running scaffolding in a sandboxed container...\n");
     const result = spawnSync("docker", [
         "run",
         "--rm",
-        "-it",
+        ...ttyFlags,
+        ...userArgs,
         ...volumes,
-        "-e",
-        "DECOHERE_BUILDER=1",
+        ...envArgs,
         "-w",
         "/workspace",
         BUILDER_IMAGE,
-        "webapi",
-        "-d",
-        "."
+        ...containerArgv
     ], {
         stdio: "inherit"
     });
+    if (result.status === 0 && kind === "scaffold") {
+        console.log(`\n  Scaffold complete!\n\n  Open your project:\n\n    code ${targetDir}\n`);
+    }
     process.exit(result.status ?? 0);
 }
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NyZWF0ZS9zcmMvcnVubmVyLnRzIl0sInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IGV4ZWNGaWxlU3luYywgc3Bhd25TeW5jIH0gZnJvbSBcIm5vZGU6Y2hpbGRfcHJvY2Vzc1wiO1xuaW1wb3J0IHsgbWtkaXJTeW5jIH0gZnJvbSBcIm5vZGU6ZnNcIjtcbmltcG9ydCB7IHJlc29sdmUgfSBmcm9tIFwibm9kZTpwYXRoXCI7XG5pbXBvcnQgeyBDUkVBVEVfVkVSU0lPTiB9IGZyb20gXCIuL3ZlcnNpb24uanNcIjtcblxuY29uc3QgQlVJTERFUl9JTUFHRSA9IGBnaGNyLmlvL2RlY29oZXJlL3NjYWZmb2xkOiR7Q1JFQVRFX1ZFUlNJT059YDtcblxuLyoqXG4gKiBSdW4gdGhlIHNjYWZmb2xkIGluc2lkZSBhIHByZS1idWlsdCBEb2NrZXIgYnVpbGRlciBpbWFnZS5cbiAqXG4gKiBDYWxsZWQgd2hlbiBgREVDT0hFUkVfQlVJTERFUmAgaXMgbm90IHNldCDigJQgaS5lLiB0aGUgQ0xJIGlzIHJ1bm5pbmcgb24gdGhlXG4gKiBob3N0LCBvdXRzaWRlIHRoZSBjb250YWluZXIuIE1vdW50cyB0aGUgdGFyZ2V0IGRpcmVjdG9yeSBhcyBgL3dvcmtzcGFjZWAgc29cbiAqIHRoZSBzY2FmZm9sZGVkIGZpbGVzIGFyZSB3cml0dGVuIGJhY2sgdG8gdGhlIGhvc3QgZmlsZXN5c3RlbS5cbiAqXG4gKiBJZiBgfi8uY29uZmlnL2F1dGgwYCBleGlzdHMgb24gdGhlIGhvc3QgdGhlIGRpcmVjdG9yeSBpcyBhbHNvIG1vdW50ZWQgc29cbiAqIHRoZSBhdXRoMCBDTEkgaW5zaWRlIHRoZSBjb250YWluZXIgY2FuIHJldXNlIGV4aXN0aW5nIGNyZWRlbnRpYWxzIHNpbGVudGx5LlxuICovXG5leHBvcnQgZnVuY3Rpb24gcnVuSW5CdWlsZGVyKG9wdHM6IHsgZD86IHN0cmluZyB9KTogbmV2ZXIge1xuXHRjb25zdCB0YXJnZXREaXIgPSByZXNvbHZlKG9wdHMuZCA/PyBcIi5cIik7XG5cdG1rZGlyU3luYyh0YXJnZXREaXIsIHsgcmVjdXJzaXZlOiB0cnVlIH0pO1xuXG5cdC8vIEVuc3VyZSBEb2NrZXIgaXMgYXZhaWxhYmxlLlxuXHR0cnkge1xuXHRcdGV4ZWNGaWxlU3luYyhcImRvY2tlclwiLCBbXCJpbmZvXCJdLCB7IHN0ZGlvOiBcInBpcGVcIiB9KTtcblx0fSBjYXRjaCB7XG5cdFx0Y29uc29sZS5lcnJvcihcblx0XHRcdFwiXFxuICBEb2NrZXIgaXMgcmVxdWlyZWQgdG8gc2NhZmZvbGQgYSBEZWNvaGVyZSBwcm9qZWN0LlxcblwiICtcblx0XHRcdFx0XCIgIEluc3RhbGwgRG9ja2VyIERlc2t0b3A6IGh0dHBzOi8vd3d3LmRvY2tlci5jb20vcHJvZHVjdHMvZG9ja2VyLWRlc2t0b3BcXG5cIixcblx0XHQpO1xuXHRcdHByb2Nlc3MuZXhpdCgxKTtcblx0fVxuXG5cdGNvbnN0IHZvbHVtZXM6IHN0cmluZ1tdID0gW1wiLXZcIiwgYCR7dGFyZ2V0RGlyfTovd29ya3NwYWNlYF07XG5cblx0Y29uc29sZS5sb2coXCIgIFJ1bm5pbmcgc2NhZmZvbGRpbmcgaW4gYSBzYW5kYm94ZWQgY29udGFpbmVyLi4uXFxuXCIpO1xuXG5cdGNvbnN0IHJlc3VsdCA9IHNwYXduU3luYyhcblx0XHRcImRvY2tlclwiLFxuXHRcdFtcblx0XHRcdFwicnVuXCIsXG5cdFx0XHRcIi0tcm1cIixcblx0XHRcdFwiLWl0XCIsXG5cdFx0XHQuLi52b2x1bWVzLFxuXHRcdFx0XCItZVwiLFxuXHRcdFx0XCJERUNPSEVSRV9CVUlMREVSPTFcIixcblx0XHRcdFwiLXdcIixcblx0XHRcdFwiL3dvcmtzcGFjZVwiLFxuXHRcdFx0QlVJTERFUl9JTUFHRSxcblx0XHRcdFwid2ViYXBpXCIsXG5cdFx0XHRcIi1kXCIsXG5cdFx0XHRcIi5cIixcblx0XHRdLFxuXHRcdHsgc3RkaW86IFwiaW5oZXJpdFwiIH0sXG5cdCk7XG5cblx0cHJvY2Vzcy5leGl0KHJlc3VsdC5zdGF0dXMgPz8gMCk7XG59XG4iXSwibmFtZXMiOlsiZXhlY0ZpbGVTeW5jIiwic3Bhd25TeW5jIiwibWtkaXJTeW5jIiwicmVzb2x2ZSIsIkNSRUFURV9WRVJTSU9OIiwiQlVJTERFUl9JTUFHRSIsInJ1bkluQnVpbGRlciIsIm9wdHMiLCJ0YXJnZXREaXIiLCJkIiwicmVjdXJzaXZlIiwic3RkaW8iLCJjb25zb2xlIiwiZXJyb3IiLCJwcm9jZXNzIiwiZXhpdCIsInZvbHVtZXMiLCJsb2ciLCJyZXN1bHQiLCJzdGF0dXMiXSwibWFwcGluZ3MiOiJBQUFBLFNBQVNBLFlBQVksRUFBRUMsU0FBUyxRQUFRLHFCQUFxQjtBQUM3RCxTQUFTQyxTQUFTLFFBQVEsVUFBVTtBQUNwQyxTQUFTQyxPQUFPLFFBQVEsWUFBWTtBQUNwQyxTQUFTQyxjQUFjLFFBQVEsZUFBZTtBQUU5QyxNQUFNQyxnQkFBZ0IsQ0FBQywwQkFBMEIsRUFBRUQsZ0JBQWdCO0FBRW5FOzs7Ozs7Ozs7Q0FTQyxHQUNELE9BQU8sU0FBU0UsYUFBYUMsSUFBb0I7SUFDaEQsTUFBTUMsWUFBWUwsUUFBUUksS0FBS0UsQ0FBQyxJQUFJO0lBQ3BDUCxVQUFVTSxXQUFXO1FBQUVFLFdBQVc7SUFBSztJQUV2Qyw4QkFBOEI7SUFDOUIsSUFBSTtRQUNIVixhQUFhLFVBQVU7WUFBQztTQUFPLEVBQUU7WUFBRVcsT0FBTztRQUFPO0lBQ2xELEVBQUUsT0FBTTtRQUNQQyxRQUFRQyxLQUFLLENBQ1osNkRBQ0M7UUFFRkMsUUFBUUMsSUFBSSxDQUFDO0lBQ2Q7SUFFQSxNQUFNQyxVQUFvQjtRQUFDO1FBQU0sR0FBR1IsVUFBVSxXQUFXLENBQUM7S0FBQztJQUUzREksUUFBUUssR0FBRyxDQUFDO0lBRVosTUFBTUMsU0FBU2pCLFVBQ2QsVUFDQTtRQUNDO1FBQ0E7UUFDQTtXQUNHZTtRQUNIO1FBQ0E7UUFDQTtRQUNBO1FBQ0FYO1FBQ0E7UUFDQTtRQUNBO0tBQ0EsRUFDRDtRQUFFTSxPQUFPO0lBQVU7SUFHcEJHLFFBQVFDLElBQUksQ0FBQ0csT0FBT0MsTUFBTSxJQUFJO0FBQy9CIn0=

package/es6/src/version.js

@@ -2,21 +2,29 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const _require = createRequire(import.meta.url);
-function resolveCreateVersion() {
+const DEFAULT_CREATE_VERSION = "0.0.1-dev";
+const DEFAULT_CREATE_IMAGE_REPOSITORY = "ghcr.io/typesmiths/decohere/create";
+function resolveCreateMetadata() {
     let dir = dirname(fileURLToPath(import.meta.url));
     for(let i = 0; i < 5; i++){
         try {
             const pkg = _require(join(dir, "package.json"));
             if (pkg.name === "@decohere/create") {
-                return pkg.version ?? "0.0.1-dev";
+                return {
+                    version: pkg.version ?? DEFAULT_CREATE_VERSION,
+                    imageRepository: pkg.decohere?.dockerImageRepository ?? DEFAULT_CREATE_IMAGE_REPOSITORY
+                };
             }
         } catch  {}
         const parent = dirname(dir);
         if (parent === dir) break;
         dir = parent;
     }
-    return "0.0.1-dev";
+    return {
+        version: DEFAULT_CREATE_VERSION,
+        imageRepository: DEFAULT_CREATE_IMAGE_REPOSITORY
+    };
 }
-/** Version of @decohere/create, used to pin scaffolded @decohere/* dependencies. */ export const CREATE_VERSION = resolveCreateVersion();
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2NyZWF0ZS9zcmMvdmVyc2lvbi50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBjcmVhdGVSZXF1aXJlIH0gZnJvbSBcIm5vZGU6bW9kdWxlXCI7XG5pbXBvcnQgeyBkaXJuYW1lLCBqb2luIH0gZnJvbSBcIm5vZGU6cGF0aFwiO1xuaW1wb3J0IHsgZmlsZVVSTFRvUGF0aCB9IGZyb20gXCJub2RlOnVybFwiO1xuXG5jb25zdCBfcmVxdWlyZSA9IGNyZWF0ZVJlcXVpcmUoaW1wb3J0Lm1ldGEudXJsKTtcblxuZnVuY3Rpb24gcmVzb2x2ZUNyZWF0ZVZlcnNpb24oKTogc3RyaW5nIHtcblx0bGV0IGRpciA9IGRpcm5hbWUoZmlsZVVSTFRvUGF0aChpbXBvcnQubWV0YS51cmwpKTtcblx0Zm9yIChsZXQgaSA9IDA7IGkgPCA1OyBpKyspIHtcblx0XHR0cnkge1xuXHRcdFx0Y29uc3QgcGtnID0gX3JlcXVpcmUoam9pbihkaXIsIFwicGFja2FnZS5qc29uXCIpKSBhcyB7XG5cdFx0XHRcdG5hbWU/OiBzdHJpbmc7XG5cdFx0XHRcdHZlcnNpb24/OiBzdHJpbmc7XG5cdFx0XHR9O1xuXHRcdFx0aWYgKHBrZy5uYW1lID09PSBcIkBkZWNvaGVyZS9jcmVhdGVcIikge1xuXHRcdFx0XHRyZXR1cm4gcGtnLnZlcnNpb24gPz8gXCIwLjAuMS1kZXZcIjtcblx0XHRcdH1cblx0XHR9IGNhdGNoIHt9XG5cdFx0Y29uc3QgcGFyZW50ID0gZGlybmFtZShkaXIpO1xuXHRcdGlmIChwYXJlbnQgPT09IGRpcikgYnJlYWs7XG5cdFx0ZGlyID0gcGFyZW50O1xuXHR9XG5cdHJldHVybiBcIjAuMC4xLWRldlwiO1xufVxuXG4vKiogVmVyc2lvbiBvZiBAZGVjb2hlcmUvY3JlYXRlLCB1c2VkIHRvIHBpbiBzY2FmZm9sZGVkIEBkZWNvaGVyZS8qIGRlcGVuZGVuY2llcy4gKi9cbmV4cG9ydCBjb25zdCBDUkVBVEVfVkVSU0lPTiA9IHJlc29sdmVDcmVhdGVWZXJzaW9uKCk7XG4iXSwibmFtZXMiOlsiY3JlYXRlUmVxdWlyZSIsImRpcm5hbWUiLCJqb2luIiwiZmlsZVVSTFRvUGF0aCIsIl9yZXF1aXJlIiwidXJsIiwicmVzb2x2ZUNyZWF0ZVZlcnNpb24iLCJkaXIiLCJpIiwicGtnIiwibmFtZSIsInZlcnNpb24iLCJwYXJlbnQiLCJDUkVBVEVfVkVSU0lPTiJdLCJtYXBwaW5ncyI6IkFBQUEsU0FBU0EsYUFBYSxRQUFRLGNBQWM7QUFDNUMsU0FBU0MsT0FBTyxFQUFFQyxJQUFJLFFBQVEsWUFBWTtBQUMxQyxTQUFTQyxhQUFhLFFBQVEsV0FBVztBQUV6QyxNQUFNQyxXQUFXSixjQUFjLFlBQVlLLEdBQUc7QUFFOUMsU0FBU0M7SUFDUixJQUFJQyxNQUFNTixRQUFRRSxjQUFjLFlBQVlFLEdBQUc7SUFDL0MsSUFBSyxJQUFJRyxJQUFJLEdBQUdBLElBQUksR0FBR0EsSUFBSztRQUMzQixJQUFJO1lBQ0gsTUFBTUMsTUFBTUwsU0FBU0YsS0FBS0ssS0FBSztZQUkvQixJQUFJRSxJQUFJQyxJQUFJLEtBQUssb0JBQW9CO2dCQUNwQyxPQUFPRCxJQUFJRSxPQUFPLElBQUk7WUFDdkI7UUFDRCxFQUFFLE9BQU0sQ0FBQztRQUNULE1BQU1DLFNBQVNYLFFBQVFNO1FBQ3ZCLElBQUlLLFdBQVdMLEtBQUs7UUFDcEJBLE1BQU1LO0lBQ1A7SUFDQSxPQUFPO0FBQ1I7QUFFQSxrRkFBa0YsR0FDbEYsT0FBTyxNQUFNQyxpQkFBaUJQLHVCQUF1QiJ9
+const createMetadata = resolveCreateMetadata();
+export const CREATE_VERSION = createMetadata.version;
+export const CREATE_IMAGE_REPOSITORY = createMetadata.imageRepository;