@mp-lb/arcnet 0.0.0-stage → 0.2.0

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");

package/src/deploy.ts

@@ -0,0 +1,71 @@
+import { rmSync } from "node:fs";
+import { fail } from "./fail.js";
+import { inspectReferences } from "./inspectReferences.js";
+import type {
+  RunProcess,
+  VercelConfig,
+  VercelRequest,
+  VercelSite,
+} from "./schemas.js";
+import { stageSite } from "./stageSite.js";
+import { validateConfig } from "./validateConfig.js";
+
+export const deploy = async (
+  config: VercelConfig,
+  root: string,
+  request: VercelRequest,
+  run: RunProcess,
+  environment: NodeJS.ProcessEnv,
+  target = "production",
+) => {
+  validateConfig(config, root);
+  if (config.approved !== true)
+    fail(
+      "Deployment disabled. Review account, project references, routing and production-trigger ownership before setting approved=true.",
+    );
+  if (!["production", "preview"].includes(target))
+    fail("Target must be production or preview.");
+  if (
+    environment.GITHUB_ACTIONS === "true" &&
+    (environment.GITHUB_REPOSITORY !== config.repository ||
+      environment.GITHUB_REF !== "refs/heads/main")
+  )
+    fail(
+      "CI deployment is restricted to the configured repository main branch.",
+    );
+  await inspectReferences(config, request); // Check every identity before building or uploading any site.
+  const stages: Array<[VercelSite, string]> = [];
+
+  try {
+    for (const site of Object.values(config.sites)) {
+      const buildEnv = Object.fromEntries(
+        Object.entries(environment).filter(([k]) => !k.startsWith("VERCEL_")),
+      );
+
+      await run(site.build[0]!, site.build.slice(1), root, buildEnv);
+      stages.push([site, stageSite(root, site, config.account)]);
+    }
+
+    for (const [site, stage] of stages) {
+      const args = [
+        "--yes",
+        "vercel@63.1.2",
+        "deploy",
+        "--prebuilt",
+        "--yes",
+        ...(target === "production" ? ["--prod"] : []),
+        "--token",
+        environment.VERCEL_TOKEN!,
+      ];
+
+      await run("npx", args, stage, {
+        ...environment,
+        VERCEL_PROJECT_ID: site.projectId,
+        VERCEL_ORG_ID: config.account.id,
+      });
+    }
+  } finally {
+    for (const [, stage] of stages)
+      rmSync(stage, { recursive: true, force: true });
+  }
+};

package/src/fail.ts

@@ -0,0 +1,3 @@
+export const fail: (message: string) => never = (message) => {
+  throw new Error(message);
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createCli } from "./createCli.js";
+export { setup } from "./setup.js";

package/src/inspectReferences.ts

@@ -0,0 +1,20 @@
+import { checkIdentity } from "./checkIdentity.js";
+import { fail } from "./fail.js";
+import type { VercelConfig, VercelRequest } from "./schemas.js";
+
+export const inspectReferences = async (
+  config: VercelConfig,
+  request: VercelRequest,
+) => {
+  for (const site of Object.values(config.sites)) {
+    if (site.mode !== "existing")
+      fail(
+        `Project ${site.projectName} is new. Create it explicitly, review and commit the returned reference before deployment.`,
+      );
+    checkIdentity(
+      await request("GET", `/v9/projects/${site.projectId}`, config.account),
+      site,
+      config.account,
+    );
+  }
+};

package/src/inspectStaticTree.ts

@@ -0,0 +1,19 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fail } from "./fail.js";
+
+export const inspectStaticTree = (path: string) => {
+  for (const name of readdirSync(path)) {
+    const p = join(path, name),
+      stat = lstatSync(p);
+
+    if (
+      stat.isSymbolicLink() ||
+      [".git", ".env", "node_modules"].includes(name) ||
+      name.startsWith(".env.")
+    )
+      fail(`Refusing unsafe static artifact entry: ${name}`);
+    if (stat.isDirectory()) inspectStaticTree(p);
+    else if (!stat.isFile()) fail("Static output contains a non-regular file.");
+  }
+};

package/src/packageInfo.ts

@@ -0,0 +1,10 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+export const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+export const packageVersion = z
+  .object({ version: z.string() })
+  .parse(
+    JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")),
+  ).version;

package/src/parseSelection.ts

@@ -0,0 +1,22 @@
+import {
+  serviceDeploySchema,
+  type ServiceDeploy,
+} from "@mp-lb/zapper/dist/arc/schemas.js";
+
+export const parseSelection = (
+  input: unknown,
+): Record<string, ServiceDeploy> => {
+  if (
+    !input ||
+    typeof input !== "object" ||
+    Array.isArray(input) ||
+    Object.keys(input).length === 0
+  )
+    throw new Error("Services file must be a nonempty JSON object.");
+  return Object.fromEntries(
+    Object.entries(input).map(([name, block]) => [
+      name,
+      serviceDeploySchema.parse(block),
+    ]),
+  );
+};

package/src/parseSetupInput.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { createSetupCommand } from "./createSetupCommand.js";
+
+const schema = z.object({
+  service: z.string(),
+  dockerfile: z.string(),
+  repository: z.string().optional(),
+  services: z.string().optional(),
+  vercel: z.string().optional(),
+  dryRun: z.boolean().default(false),
+});
+
+export const parseSetupInput = (args: string[]) => {
+  const command = createSetupCommand()
+    .exitOverride()
+    .configureOutput({ writeErr: () => {} });
+
+  // Commander owns argument parsing; reject duplicate flags instead of silently taking the last value.
+  const flags = args.filter((value) => value.startsWith("--"));
+  if (new Set(flags).size !== flags.length)
+    throw new Error("Duplicate setup option.");
+  command.parse(args, { from: "user" });
+
+  const slug = z
+    .string()
+    .max(23)
+    .regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/)
+    .parse(command.args[0]);
+
+  const input = schema.parse(command.opts());
+
+  const options = {
+    ...input,
+    "seen-service": command.getOptionValueSource("service") === "cli",
+    "seen-dockerfile": command.getOptionValueSource("dockerfile") === "cli",
+    "seen-repository": command.getOptionValueSource("repository") === "cli",
+  };
+
+  return { slug, options, dry: input.dryRun };
+};

package/src/readSelection.ts

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fail } from "./fail.js";
+import { parseSelection } from "./parseSelection.js";
+const read = (path: string) => readFileSync(path, "utf8");
+
+export const readSelection = (file: string, safe: (name: string) => string) => {
+  const input: unknown = JSON.parse(read(safe(file)));
+  const selection = parseSelection(input);
+
+  const supported = [
+    "cloud-run-web",
+    "gce-worker",
+    "vercel-static",
+    "shared-mongo-atlas",
+    "upstash-redis",
+    "aws-s3",
+  ];
+
+  for (const [name, block] of Object.entries(selection)) {
+    if (
+      !/^[a-z][a-z0-9-]*$/.test(name) ||
+      ["gcp", "registry", "ci", "myshop"].includes(name) ||
+      /myshop/i.test(JSON.stringify(block))
+    )
+      fail(
+        "Invalid service selection: MyShop is local-only and project module names are reserved.",
+      );
+    if (!supported.includes(block.module))
+      fail(
+        `Unsupported starter module: ${block.module}. Use a reviewed custom Arc manifest.`,
+      );
+    if (
+      ["cloud-run-web", "gce-worker"].includes(block.module) &&
+      (!block.dockerfile || !existsSync(safe(block.dockerfile)))
+    )
+      fail(`Service ${name} requires an existing explicit Dockerfile.`);
+    if (
+      ["cloud-run-web", "vercel-static"].includes(block.module) &&
+      (!block.domain || !/^[a-z0-9.-]+$/.test(block.domain))
+    )
+      fail(`Service ${name} requires an explicit domain.`);
+    if (block["deploy-path"]) safe(block["deploy-path"]);
+    if (block["local-config"]) safe(block["local-config"]);
+  }
+
+  return selection;
+};

package/src/renderPlan.ts

@@ -0,0 +1,27 @@
+import type { VercelConfig } from "./schemas.js";
+import { validateConfig } from "./validateConfig.js";
+
+export const renderPlan = (config: VercelConfig, root: string) => {
+  validateConfig(config, root);
+  return {
+    mode: "vercel",
+    account: config.account,
+    approved: config.approved,
+    terraform: false,
+    changesProjectSettings: false,
+    changesDNS: false,
+    sites: Object.entries(config.sites).map(([name, site]) => ({
+      name,
+      operation:
+        site.mode === "new"
+          ? "explicit-create-required-before-deploy"
+          : "reference-existing",
+      projectId: site.projectId ?? null,
+      projectName: site.projectName,
+      build: site.build,
+      output: site.output,
+      outputConfig: site.outputConfig,
+      deployment: "prebuilt-static",
+    })),
+  };
+};

package/src/renderResult.ts

@@ -0,0 +1,18 @@
+export const renderResult = (
+  value: unknown,
+  options: { json?: boolean; jsonl?: boolean },
+) => {
+  if (options.json && options.jsonl)
+    throw new Error("Choose either --json or --jsonl.");
+  if (options.jsonl)
+    return JSON.stringify({ type: "command.completed", result: value });
+  if (options.json) return JSON.stringify(value);
+  if (
+    value &&
+    typeof value === "object" &&
+    "message" in value &&
+    typeof value.message === "string"
+  )
+    return value.message;
+  return JSON.stringify(value, null, 2);
+};

package/src/resolveRepository.ts

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+import { fail } from "./fail.js";
+
+export const resolveRepository = (
+  root: string,
+  configured?: string,
+): string => {
+  let repository = configured;
+
+  if (!repository) {
+    let origin;
+
+    try {
+      origin = execFileSync("git", ["remote", "get-url", "origin"], {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      fail("Cannot read Git origin. Pass --repository owner/repo.");
+    }
+
+    repository =
+      /^(?:git@github\.com:|https:\/\/github\.com\/)([^/]+\/[^/]+?)(?:\.git)?$/.exec(
+        origin!,
+      )?.[1];
+  }
+
+  if (
+    !/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(
+      repository ?? "",
+    )
+  )
+    fail(
+      "Repository must be an explicit GitHub owner/repo (or a GitHub origin).",
+    );
+  return repository!;
+};

package/src/runProcess.ts

@@ -0,0 +1,26 @@
+import { spawnSync } from "node:child_process";
+
+export const runProcess = (
+  command: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  machine = false,
+  input?: string,
+) => {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    input,
+    stdio: [
+      input === undefined ? "ignore" : "pipe",
+      machine ? 2 : "inherit",
+      "inherit",
+    ],
+  });
+
+  if (result.error || result.status !== 0)
+    throw new Error(
+      `${command} failed (${result.status ?? "could not start"}). No automatic retry; earlier cloud changes may have succeeded.`,
+    );
+};

package/src/runTerraform.ts

@@ -0,0 +1,182 @@
+import { loadManifest } from "@mp-lb/zapper/dist/arc/manifest.js";
+import { resolveModules } from "@mp-lb/zapper/dist/arc/modules.js";
+import {
+  deployBlockSchema,
+  networkConfigSchema,
+} from "@mp-lb/zapper/dist/arc/schemas.js";
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { devNull, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { runProcess } from "./runProcess.js";
+import { envPoolSchema, terraformConfigSchema } from "./schemas.js";
+const require = createRequire(import.meta.url);
+
+export const runTerraform = (
+  command: "check" | "plan" | "deploy",
+  root: string,
+  machine = false,
+) => {
+  const here = join(root, ".arcnet");
+  const read = (name: string) => readFileSync(join(here, name), "utf8");
+  const config = terraformConfigSchema.parse(JSON.parse(read("project.json")));
+  const zap = parse(readFileSync(join(root, "zap.yaml"), "utf8"));
+  const network = networkConfigSchema.parse(parse(read("network.yaml")));
+  const deployment = deployBlockSchema.parse(zap.deploy);
+  if (config.version !== 1 || zap.project !== config.slug)
+    throw new Error("Project config does not match zap.yaml.");
+  const services = Object.keys(deployment?.services ?? {});
+  if (
+    JSON.stringify(services.sort()) !==
+      JSON.stringify([...config.services].sort()) ||
+    /myshop/i.test(JSON.stringify(deployment.services))
+  )
+    throw new Error(
+      "Service selection differs or includes local-only MyShop. Review scope before deployment.",
+    );
+  const blocks = Object.values(deployment.services);
+  for (const service of blocks)
+    if (
+      ["cloud-run-web", "gce-worker"].includes(service.module) &&
+      (!service.dockerfile || !existsSync(join(root, service.dockerfile)))
+    )
+      throw new Error("Container Dockerfile is missing.");
+  if (deployment.project?.ci?.params?.repository !== config.repository)
+    throw new Error(
+      "Deployment manifest repository differs from project config.",
+    );
+
+  const publicEnv: unknown = existsSync(join(here, "env.production.json"))
+    ? JSON.parse(read("env.production.json"))
+    : {};
+
+  let secretEnv;
+
+  try {
+    secretEnv = JSON.parse(process.env.ARCNET_ENV_JSON || "{}");
+  } catch {
+    throw new Error("ARCNET_ENV_JSON must be valid JSON (value omitted).");
+  }
+
+  for (const pool of [publicEnv, secretEnv])
+    if (
+      !pool ||
+      Array.isArray(pool) ||
+      typeof pool !== "object" ||
+      Object.entries(pool).some(
+        ([k, v]) => !/^[A-Z_][A-Z0-9_]*$/.test(k) || typeof v !== "string",
+      )
+    )
+      throw new Error(
+        "Environment pools must be JSON objects mapping environment names to strings.",
+      );
+
+  const envPool = {
+    ...envPoolSchema.parse(publicEnv),
+    ...envPoolSchema.parse(secretEnv),
+  };
+
+  if (command === "check") {
+    return {
+      operation: command,
+      message:
+        "Offline config check passed. Cloud access, image runtime and live deployment have NOT been verified.",
+    };
+  }
+
+  if (command === "deploy" && config.approved !== true)
+    throw new Error(
+      "Deployment disabled. Complete prerequisites and obtain target/cost/IAM/DNS approval before committing approved=true.",
+    );
+
+  if (process.env.GITHUB_ACTIONS === "true") {
+    if (
+      process.env.GITHUB_REPOSITORY !== config.repository ||
+      process.env.GITHUB_REF !== "refs/heads/main"
+    )
+      throw new Error(
+        "CI deployment is restricted to the configured repository main branch.",
+      );
+    if (
+      !/^projects\/\d+\/locations\/global\/workloadIdentityPools\/github\/providers\/github-actions$/.test(
+        config.workloadIdentityProvider,
+      )
+    )
+      throw new Error(
+        "Set workloadIdentityProvider from the approved first deployment.",
+      );
+  }
+
+  const modulesDir = resolve(
+    dirname(require.resolve("@mp-lb/zapper")),
+    "../arc",
+  );
+
+  const instances = resolveModules(loadManifest(root), modulesDir, root);
+  for (const instance of instances)
+    for (const credential of instance.manifest.credentials)
+      if (!process.env[credential.name])
+        throw new Error(
+          `${credential.name} is required for ${instance.key}; supply a scoped operator credential through environment, never commit it.`,
+        );
+  if (JSON.stringify(network).includes("REPLACE_"))
+    throw new Error(
+      "Network contains REPLACE_ placeholders. Commit reviewed network/billing settings before planning or deployment.",
+    );
+
+  const missing = blocks
+    .flatMap((service) => service.env ?? [])
+    .filter((key) => !key.includes("=") && !Object.hasOwn(envPool, key));
+
+  if (missing.length)
+    throw new Error(
+      `Missing app environment keys: ${missing.join(", ")}. Supply ARCNET_ENV_JSON or committed public env.`,
+    );
+  for (const tool of [
+    "terraform",
+    "gcloud",
+    ...(blocks.some((s) => ["cloud-run-web", "gce-worker"].includes(s.module))
+      ? ["docker"]
+      : []),
+  ])
+    if (spawnSync(tool, ["--version"], { stdio: "ignore" }).status !== 0)
+      throw new Error(
+        `Required executable unavailable: ${tool}. See StackForge ArcNet prerequisites.`,
+      );
+  const executable = require.resolve("@mp-lb/zapper");
+  // The engine requires a file for operator configuration. Keep this transient,
+  // and explicitly disable its machine-global credentials fallback.
+  const temporary = mkdtempSync(join(tmpdir(), "arcnet-operator-"));
+
+  try {
+    const operator = join(temporary, "operator.json");
+    writeFileSync(operator, JSON.stringify({ credentials: devNull }), {
+      mode: 0o600,
+    });
+
+    runProcess(
+      process.execPath,
+      [executable, "arc", command],
+      root,
+      {
+        ...process.env,
+        ZAP_ARC_NETWORK_FILE: join(here, "network.yaml"),
+        ZAP_ARC_CONFIG: operator,
+      },
+      machine,
+      JSON.stringify(envPool),
+    );
+
+    return { operation: command, message: `Zap Arc ${command} completed.` };
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+};