@mp-lb/arcnet 0.0.0-stage → 0.1.0

package/dist/stageSite.js

@@ -0,0 +1,31 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fail } from "./fail.js";
+import { inspectStaticTree } from "./inspectStaticTree.js";
+import { safePath } from "./safePath.js";
+export const stageSite = (root, site, account) => {
+    const output = safePath(root, site.output);
+    if (!existsSync(output) ||
+        !lstatSync(output).isDirectory() ||
+        !existsSync(join(output, "index.html")))
+        fail(`Static output needs index.html: ${site.output}`);
+    inspectStaticTree(output);
+    const stage = mkdtempSync(join(tmpdir(), "arcnet-static-"));
+    try {
+        mkdirSync(join(stage, ".vercel/output"), { recursive: true });
+        cpSync(output, join(stage, ".vercel/output/static"), { recursive: true });
+        writeFileSync(join(stage, ".vercel/output/config.json"), JSON.stringify(site.outputConfig));
+        writeFileSync(join(stage, ".vercel/project.json"), JSON.stringify({
+            projectId: site.projectId,
+            orgId: account.id,
+            projectName: site.projectName,
+        }));
+        return stage;
+    }
+    catch (e) {
+        rmSync(stage, { recursive: true, force: true });
+        throw e;
+    }
+};
+//# sourceMappingURL=stageSite.js.map

package/dist/stageSite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stageSite.js","sourceRoot":"","sources":["../src/stageSite.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,UAAU,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,MAAM,EACN,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,IAAY,EACZ,IAAgB,EAChB,OAAsB,EACtB,EAAE;IACF,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3C,IACE,CAAC,UAAU,CAAC,MAAM,CAAC;QACnB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE;QAChC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAEvC,IAAI,CAAC,mCAAmC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAE5D,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9D,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,uBAAuB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,aAAa,CACX,IAAI,CAAC,KAAK,EAAE,4BAA4B,CAAC,EACzC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,CAClC,CAAC;QAEF,aAAa,CACX,IAAI,CAAC,KAAK,EAAE,sBAAsB,CAAC,EACnC,IAAI,CAAC,SAAS,CAAC;YACb,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,OAAO,CAAC,EAAE;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CACH,CAAC;QAEF,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC,CAAC"}

package/dist/validateConfig.d.ts

@@ -0,0 +1,3 @@
+import type { VercelConfig } from "./schemas.js";
+export declare const validateConfig: (input: unknown, root: string) => VercelConfig;
+//# sourceMappingURL=validateConfig.d.ts.map

package/dist/validateConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateConfig.d.ts","sourceRoot":"","sources":["../src/validateConfig.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,EAAE,MAAM,MAAM,KAAG,YAgB7D,CAAC"}

package/dist/validateConfig.js

@@ -0,0 +1,17 @@
+import { fail } from "./fail.js";
+import { safePath } from "./safePath.js";
+import { vercelConfigSchema } from "./schemas.js";
+export const validateConfig = (input, root) => {
+    const config = vercelConfigSchema.parse(input);
+    const identities = new Set();
+    for (const site of Object.values(config.sites)) {
+        for (const id of [site.projectId, site.projectName].filter((id) => Boolean(id))) {
+            if (identities.has(id))
+                fail("Duplicate Vercel project selection.");
+            identities.add(id);
+        }
+        safePath(root, site.output);
+    }
+    return config;
+};
+//# sourceMappingURL=validateConfig.js.map

package/dist/validateConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateConfig.js","sourceRoot":"","sources":["../src/validateConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAAE,IAAY,EAAgB,EAAE;IAC3E,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,KAAK,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,CACxD,CAAC,EAAE,EAAgB,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAClC,EAAE,CAAC;YACF,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,IAAI,CAAC,qCAAqC,CAAC,CAAC;YACpE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;QAED,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/docs/public/commands.md

@@ -0,0 +1,58 @@
+# ArcNet command reference
+
+Generated from the CLI command tree.
+
+## Global Options
+
+| Option | Description |
+| --- | --- |
+| `-V, --version` | output the version number |
+| `--root <directory>` | Target project root |
+| `--json` | Render one JSON result |
+| `--jsonl` | Render structured completion events |
+| `--noninteractive` | Run without prompts (all commands are noninteractive) |
+
+## `arcnet version`
+
+Show the installed package version.
+
+## `arcnet setup <slug>`
+
+Add ArcNet configuration and workflow; pin the CLI in the project manifest.
+
+| Option | Description |
+| --- | --- |
+| `--dry-run` | Report generated files without writing |
+| `--service <name>` | Default container service |
+| `--dockerfile <path>` | Container Dockerfile |
+| `--repository <owner/repo>` | GitHub repository (defaults to origin) |
+| `--services <path>` | Explicit service selection JSON |
+| `--vercel <path>` | Static Vercel references JSON |
+
+## `arcnet check`
+
+Validate project configuration offline.
+
+## `arcnet plan`
+
+Plan deployment (Terraform contacts providers; static Vercel stays offline).
+
+## `arcnet deploy`
+
+Deploy the approved project.
+
+## `arcnet preview`
+
+Deploy static Vercel sites to preview.
+
+## `arcnet inspect`
+
+Verify static Vercel project identities remotely.
+
+## `arcnet create <site>`
+
+Create one explicitly approved Vercel project.
+
+## `arcnet ci`
+
+Validate deployment identity and write GitHub Actions outputs.

package/docs/public/llms-full.txt

@@ -0,0 +1,79 @@
+# @mp-lb/arcnet
+
+ArcNet's TypeScript CLI for installing deployment configuration and deploying projects. The package owns shared runners, validation, workflow templates and the Vercel Terraform module; projects keep configuration and application-specific Dockerfiles.
+
+**Release status:** implementation and checks are complete; the first npm publication is blocked by registry authentication. The commands below target the pending `0.1.0` release.
+
+From an existing project with Zap, GitHub, and pinned pnpm:
+
+```sh
+pnpm dlx @mp-lb/arcnet@0.1.0 setup hello-world --dry-run
+pnpm dlx @mp-lb/arcnet@0.1.0 setup hello-world
+pnpm install
+pnpm exec arcnet check
+```
+
+Setup pins this package in the existing root manifest. Commit the resulting lockfile. Deployment starts disabled, and setup never provisions cloud resources. Upgrades use the project's normal dependency workflow.
+
+[Project setup](https://github.com/mp-lb/stackforge/blob/main/arcnet/SETUP.md) · [Environment setup](https://github.com/mp-lb/stackforge/blob/main/arcnet/environment/setup.md) · [Audit](https://github.com/mp-lb/stackforge/blob/main/arcnet/AUDIT.md) · [Command reference](docs/public/commands.md)
+
+Zap Arc remains the pinned Terraform engine dependency. Environment bootstrap, health checks and teardown are not implemented by this package yet. The static Vercel adapter retains its existing static-only and explicit-project-reference limitations.
+
+# ArcNet command reference
+
+Generated from the CLI command tree.
+
+## Global Options
+
+| Option | Description |
+| --- | --- |
+| `-V, --version` | output the version number |
+| `--root <directory>` | Target project root |
+| `--json` | Render one JSON result |
+| `--jsonl` | Render structured completion events |
+| `--noninteractive` | Run without prompts (all commands are noninteractive) |
+
+## `arcnet version`
+
+Show the installed package version.
+
+## `arcnet setup <slug>`
+
+Add ArcNet configuration and workflow; pin the CLI in the project manifest.
+
+| Option | Description |
+| --- | --- |
+| `--dry-run` | Report generated files without writing |
+| `--service <name>` | Default container service |
+| `--dockerfile <path>` | Container Dockerfile |
+| `--repository <owner/repo>` | GitHub repository (defaults to origin) |
+| `--services <path>` | Explicit service selection JSON |
+| `--vercel <path>` | Static Vercel references JSON |
+
+## `arcnet check`
+
+Validate project configuration offline.
+
+## `arcnet plan`
+
+Plan deployment (Terraform contacts providers; static Vercel stays offline).
+
+## `arcnet deploy`
+
+Deploy the approved project.
+
+## `arcnet preview`
+
+Deploy static Vercel sites to preview.
+
+## `arcnet inspect`
+
+Verify static Vercel project identities remotely.
+
+## `arcnet create <site>`
+
+Create one explicitly approved Vercel project.
+
+## `arcnet ci`
+
+Validate deployment identity and write GitHub Actions outputs.

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@mp-lb/arcnet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "ArcNet project installation and deployment CLI.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "arcnet": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "docs/public",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mp-lb/tools.git",
+    "directory": "packages/arcnet"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mp-lb/zapper": "0.21.0",
+    "commander": "14.0.3",
+    "yaml": "2.8.1",
+    "zod": "4.4.1"
+  },
+  "devDependencies": {
+    "@mp-lb/cli-docs": "0.0.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc --project tsconfig.json && chmod +x dist/cli.js",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "test": "pnpm build && node --import tsx --test test/*.test.ts && pnpm docs:check",
+    "docs:gen": "pnpm --filter @mp-lb/cli-docs build && tsx scripts/generateDocs.ts",
+    "docs:check": "pnpm --filter @mp-lb/cli-docs build && tsx scripts/generateDocs.ts --check"
+  }
 }

package/src/addDependency.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { packageVersion } from "./packageInfo.js";
+
+const manifestSchema = z
+  .object({
+    dependencies: z.record(z.string(), z.string()).optional(),
+    devDependencies: z.record(z.string(), z.string()).optional(),
+  })
+  .passthrough();
+
+export const addDependency = (path: string) => {
+  const manifest = manifestSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+
+  const existing =
+    manifest.dependencies?.["@mp-lb/arcnet"] ??
+    manifest.devDependencies?.["@mp-lb/arcnet"];
+
+  if (existing && existing !== packageVersion)
+    throw new Error(
+      "Existing ArcNet dependency differs; review its version before setup.",
+    );
+  if (!manifest.dependencies?.["@mp-lb/arcnet"])
+    manifest.devDependencies = {
+      ...manifest.devDependencies,
+      "@mp-lb/arcnet": packageVersion,
+    };
+  return JSON.stringify(manifest, null, 2) + "\n";
+};
+
+export const hasDependency = (root: string) => {
+  const manifest = manifestSchema.parse(
+    JSON.parse(readFileSync(join(root, "package.json"), "utf8")),
+  );
+
+  return Boolean(
+    manifest.dependencies?.["@mp-lb/arcnet"] ??
+    manifest.devDependencies?.["@mp-lb/arcnet"],
+  );
+};

package/src/apiClient.ts

@@ -0,0 +1,51 @@
+import { fail } from "./fail.js";
+import type { VercelRequest } from "./schemas.js";
+import { vercelResponseSchema } from "./schemas.js";
+
+export const apiClient = (
+  token: string | undefined,
+  fetcher: typeof fetch = fetch,
+): VercelRequest => {
+  if (!token)
+    fail(
+      "VERCEL_TOKEN is required for remote operations; check and plan remain offline.",
+    );
+
+  return async (method, path, account, body) => {
+    const url = new URL(path, "https://api.vercel.com");
+    if (account.type === "team") url.searchParams.set("teamId", account.id);
+    let response;
+
+    try {
+      response = await fetcher(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(30000),
+      });
+    } catch {
+      fail(
+        method === "POST"
+          ? "Creation outcome uncertain. Inspect the named project before retrying; no automatic retry was attempted."
+          : "Vercel read failed; no changes attempted.",
+      );
+    }
+
+    if (response.status === 404 && method === "GET") return null;
+    if (!response.ok)
+      fail(
+        `Vercel ${method} failed (HTTP ${response.status}). Check scope/access; response content omitted.`,
+      );
+
+    try {
+      return vercelResponseSchema.parse(await response.json());
+    } catch {
+      fail(
+        "Vercel returned an invalid response; inspect the project before retrying.",
+      );
+    }
+  };
+};

package/src/checkIdentity.ts

@@ -0,0 +1,18 @@
+import { fail } from "./fail.js";
+import type { VercelAccount, VercelResponse, VercelSite } from "./schemas.js";
+
+export const checkIdentity = (
+  project: VercelResponse | null,
+  site: VercelSite,
+  account: VercelAccount,
+) => {
+  if (
+    !project ||
+    project.id !== site.projectId ||
+    project.name !== site.projectName ||
+    project.accountId !== account.id
+  )
+    fail(
+      `Project identity/scope mismatch for ${site.projectName}. No deployment attempted.`,
+    );
+};

package/src/ciOutputs.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { z } from "zod";
+import { terraformConfigSchema } from "./schemas.js";
+import { validateConfig } from "./validateConfig.js";
+
+export const ciOutputs = (root: string): Record<string, string> => {
+  const input: unknown = JSON.parse(
+    readFileSync(join(root, ".arcnet/project.json"), "utf8"),
+  );
+
+  if (
+    z.object({ mode: z.string().optional() }).parse(input).mode === "vercel"
+  ) {
+    const c = validateConfig(input, root);
+    return {
+      approved: String(
+        c.approved &&
+          Object.values(c.sites).every((s) => s.mode === "existing"),
+      ),
+    };
+  }
+
+  const c = terraformConfigSchema.parse(input);
+
+  const n = z
+    .object({ region: z.string().regex(/^[a-z]+-[a-z]+[0-9]$/) })
+    .parse(parse(readFileSync(join(root, ".arcnet/network.yaml"), "utf8")));
+
+  if (
+    c.approved &&
+    (!/^projects\/\d+\/locations\/global\/workloadIdentityPools\/github\/providers\/github-actions$/.test(
+      c.workloadIdentityProvider,
+    ) ||
+      !/^arc-deploy@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/.test(
+        c.serviceAccount,
+      ))
+  )
+    throw new Error("Complete WIF configuration before approval.");
+  return {
+    approved: String(c.approved),
+    provider: c.approved ? c.workloadIdentityProvider : "",
+    account: c.approved ? c.serviceAccount : "",
+    registry: `${n.region}-docker.pkg.dev`,
+  };
+};

package/src/cli.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { createCli } from "./createCli.js";
+await createCli()
+  .parseAsync()
+  .catch((error: unknown) => {
+    process.stderr.write(
+      `ArcNet: ${error instanceof Error ? error.message : "Command failed"}\n`,
+    );
+
+    process.exitCode = 1;
+  });

package/src/createCli.ts

@@ -0,0 +1,118 @@
+import { Command } from "commander";
+import { appendFileSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { ciOutputs } from "./ciOutputs.js";
+import { createSetupCommand } from "./createSetupCommand.js";
+import { packageVersion } from "./packageInfo.js";
+import { renderResult } from "./renderResult.js";
+import { runTerraform } from "./runTerraform.js";
+import { runVercel } from "./runVercel.js";
+import { setup } from "./setup.js";
+
+export const createCli = () => {
+  const cli = new Command("arcnet")
+    .description("Install and deploy ArcNet projects.")
+    .version(packageVersion)
+    .option("--root <directory>", "Target project root", process.cwd())
+    .option("--json", "Render one JSON result")
+    .option("--jsonl", "Render structured completion events")
+    .option(
+      "--noninteractive",
+      "Run without prompts (all commands are noninteractive)",
+    );
+
+  cli.hook("preAction", () => {
+    if (cli.opts().json && cli.opts().jsonl)
+      throw new Error("Choose either --json or --jsonl.");
+  });
+
+  const output = (result: unknown) => {
+    process.stdout.write(renderResult(result, cli.opts()) + "\n");
+  };
+
+  cli
+    .command("version")
+    .description("Show the installed package version.")
+    .action(() => output({ version: packageVersion }));
+
+  const install = createSetupCommand();
+  install.action(() =>
+    output({
+      ...setup(
+        install.args.concat(
+          install.options.flatMap((option) => {
+            const key = option.attributeName();
+            if (install.getOptionValueSource(key) !== "cli") return [];
+            const value: unknown = install.opts()[key];
+            return value === true
+              ? [option.long!]
+              : [option.long!, String(value)];
+          }),
+        ),
+        realpathSync(cli.opts().root),
+      ),
+    }),
+  );
+
+  cli.addCommand(install);
+
+  for (const [name, description] of Object.entries({
+    check: "Validate project configuration offline.",
+    plan: "Plan deployment (Terraform contacts providers; static Vercel stays offline).",
+    deploy: "Deploy the approved project.",
+    preview: "Deploy static Vercel sites to preview.",
+    inspect: "Verify static Vercel project identities remotely.",
+    create: "Create one explicitly approved Vercel project.",
+  })) {
+    const command = cli.command(name).description(description);
+    if (name === "create") command.argument("<site>", "Configured site name");
+    command.action(async (site: unknown) => {
+      const root = realpathSync(cli.opts().root);
+
+      const mode = z
+        .object({ mode: z.string().optional() })
+        .parse(
+          JSON.parse(readFileSync(join(root, ".arcnet/project.json"), "utf8")),
+        ).mode;
+
+      const machine = Boolean(cli.opts().json || cli.opts().jsonl);
+      if (mode === "vercel")
+        output(
+          await runVercel(
+            name,
+            root,
+            typeof site === "string" ? site : undefined,
+            machine,
+          ),
+        );
+      else if (name === "check" || name === "plan" || name === "deploy")
+        output(runTerraform(name, root, machine));
+      else
+        throw new Error(
+          `${name} is only supported for static Vercel references.`,
+        );
+    });
+  }
+
+  cli
+    .command("ci")
+    .description(
+      "Validate deployment identity and write GitHub Actions outputs.",
+    )
+    .action(() => {
+      const outputs = ciOutputs(realpathSync(cli.opts().root));
+      if (!process.env.GITHUB_OUTPUT)
+        throw new Error("GITHUB_OUTPUT is required for the ci command.");
+      appendFileSync(
+        process.env.GITHUB_OUTPUT,
+        Object.entries(outputs)
+          .map(([key, value]) => `${key}=${value}\n`)
+          .join(""),
+      );
+
+      output(outputs);
+    });
+
+  return cli;
+};

package/src/createProject.ts

@@ -0,0 +1,66 @@
+import { checkIdentity } from "./checkIdentity.js";
+import { fail } from "./fail.js";
+import type { VercelConfig, VercelRequest } from "./schemas.js";
+
+export const createProject = async (
+  config: VercelConfig,
+  name: string,
+  request: VercelRequest,
+) => {
+  const site = config.sites[name];
+  if (!site) fail("Choose a configured site.");
+
+  if (site.mode === "existing") {
+    checkIdentity(
+      await request("GET", `/v9/projects/${site.projectId}`, config.account),
+      site,
+      config.account,
+    );
+
+    return config;
+  }
+
+  if (site.creationApproved !== true)
+    fail(
+      "Project creation disabled. Obtain explicit target/cost approval and set creationApproved=true for this site.",
+    );
+
+  if (config.account.type === "personal") {
+    const who = await request("GET", "/v2/user", config.account);
+    if (who?.user?.id !== config.account.id)
+      fail(
+        "Token personal account does not match configured account; no project created.",
+      );
+  }
+
+  if (
+    await request(
+      "GET",
+      `/v9/projects/${encodeURIComponent(site.projectName)}`,
+      config.account,
+    )
+  )
+    fail(
+      `Project name ${site.projectName} already exists. Set an explicit existing reference after verifying its ID; no duplicate project was created.`,
+    );
+
+  const created = await request("POST", "/v11/projects", config.account, {
+    name: site.projectName,
+    framework: null,
+  });
+
+  if (
+    !created ||
+    !/^prj_[A-Za-z0-9]+$/.test(created.id ?? "") ||
+    created.accountId !== config.account.id ||
+    created.name !== site.projectName
+  )
+    fail(
+      "Creation response identity mismatch. Inspect the account before retrying.",
+    );
+  const next = structuredClone(config);
+  next.approved = false;
+  next.sites[name] = { ...site, mode: "existing", projectId: created.id! };
+  delete next.sites[name]!.creationApproved;
+  return next;
+};

package/src/createSetupCommand.ts

@@ -0,0 +1,16 @@
+import { Command } from "commander";
+export const createSetupCommand = () =>
+  new Command("setup")
+    .description(
+      "Add ArcNet configuration and workflow; pin the CLI in the project manifest.",
+    )
+    .argument("<slug>", "Project slug matching zap.yaml")
+    .option("--dry-run", "Report generated files without writing")
+    .option("--service <name>", "Default container service", "backend")
+    .option("--dockerfile <path>", "Container Dockerfile", ".arcnet/Dockerfile")
+    .option(
+      "--repository <owner/repo>",
+      "GitHub repository (defaults to origin)",
+    )
+    .option("--services <path>", "Explicit service selection JSON")
+    .option("--vercel <path>", "Static Vercel references JSON");