@mp-lb/arcnet 0.0.0-stage → 0.2.0

package/src/runVercel.ts

@@ -0,0 +1,77 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { apiClient } from "./apiClient.js";
+import { createProject } from "./createProject.js";
+import { deploy } from "./deploy.js";
+import { inspectReferences } from "./inspectReferences.js";
+import { renderPlan } from "./renderPlan.js";
+import { runProcess } from "./runProcess.js";
+import { validateConfig } from "./validateConfig.js";
+
+export const runVercel = async (
+  command: string,
+  root: string,
+  argument?: string,
+  machine = false,
+) => {
+  const path = join(root, ".arcnet/project.json");
+  const original = readFileSync(path, "utf8");
+  const config = validateConfig(JSON.parse(original), root);
+  if (command === "check" || command === "plan")
+    return renderPlan(config, root);
+  if (command === "create" && process.env.GITHUB_ACTIONS === "true")
+    throw new Error(
+      "Project creation is a separate local operator step, never a CI side effect.",
+    );
+  if (["deploy", "preview"].includes(command) && !config.approved)
+    throw new Error(
+      "Deployment disabled (approved=false). No remote calls made.",
+    );
+  const request = apiClient(process.env.VERCEL_TOKEN);
+
+  if (command === "inspect") {
+    await inspectReferences(config, request);
+    return {
+      operation: command,
+      message:
+        "All existing project IDs, names and account scopes match. No settings or DNS changed.",
+    };
+  }
+
+  if (command === "create") {
+    if (!argument) throw new Error("Choose a configured site.");
+    const next = await createProject(config, argument, request);
+    if (next === config)
+      return {
+        operation: command,
+        message:
+          "Already an existing reference; identity verified, nothing created.",
+      };
+    if (readFileSync(path, "utf8") !== original)
+      throw new Error(
+        `Config changed during creation. Recover the created project ID ${next.sites[argument]!.projectId} manually; no local settings overwritten.`,
+      );
+    writeFileSync(`${path}.new`, JSON.stringify(next, null, 2) + "\n", {
+      flag: "wx",
+    });
+
+    renameSync(`${path}.new`, path);
+    return {
+      operation: command,
+      projectId: next.sites[argument]!.projectId,
+      message:
+        "Created project; review and commit project.json before CI. Deployment remains disabled.",
+    };
+  }
+
+  await deploy(
+    config,
+    root,
+    request,
+    (cmd, args, cwd, env) => runProcess(cmd, args, cwd, env, machine),
+    process.env,
+    command === "preview" ? "preview" : "production",
+  );
+
+  return { operation: command, message: "Selected static sites deployed." };
+};

package/src/safePath.ts

@@ -0,0 +1,43 @@
+import { lstatSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { fail } from "./fail.js";
+
+export const safePath = (root: string, name: string) => {
+  if (
+    typeof name !== "string" ||
+    !name ||
+    isAbsolute(name) ||
+    name.includes("\\")
+  )
+    fail("Expected a project-relative path.");
+
+  const target = resolve(root, name),
+    rel = relative(root, target);
+
+  if (
+    !rel ||
+    rel === ".." ||
+    rel.startsWith("../") ||
+    rel
+      .split("/")
+      .some((p) => [".git", "node_modules", ".arcnet"].includes(p)) ||
+    /^apps\/myshop(?:\/|$)/i.test(rel)
+  )
+    fail(`Unsafe or local-only artifact path: ${name}`);
+  let at = root;
+
+  for (const part of rel.split("/")) {
+    at = join(at, part);
+    let stat;
+
+    try {
+      stat = lstatSync(at);
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+    }
+
+    if (stat?.isSymbolicLink()) fail(`Symlink not allowed: ${name}`);
+  }
+
+  return target;
+};

package/src/safeTargetPath.ts

@@ -0,0 +1,32 @@
+import { lstatSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { fail } from "./fail.js";
+
+export const safeTargetPath = (root: string, name: string) => {
+  const target = resolve(root, name);
+  if (
+    !name ||
+    isAbsolute(name) ||
+    relative(root, target) === ".." ||
+    relative(root, target).startsWith("../")
+  )
+    fail(`Path must stay within the project: ${name}`);
+  let at = root;
+
+  for (const part of relative(root, target).split("/")) {
+    at = join(at, part);
+    let stat;
+
+    try {
+      stat = lstatSync(at);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+
+    if (stat?.isSymbolicLink()) fail(`Refusing symlink: ${name}`);
+    if (stat && at !== target && !stat.isDirectory())
+      fail(`Parent path is not a directory: ${name}`);
+  }
+
+  return target;
+};

package/src/schemas.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+
+const projectName = z
+  .string()
+  .regex(/^[a-z0-9][a-z0-9-]{0,99}$/)
+  .refine((v) => !/REPLACE/i.test(v));
+
+const accountSchema = z
+  .object({
+    type: z.enum(["team", "personal"]),
+    id: z
+      .string()
+      .regex(/^[A-Za-z0-9_]{3,128}$/)
+      .refine((v) => !/REPLACE/i.test(v)),
+  })
+  .strict()
+  .refine(
+    (a) => a.type !== "team" || a.id.startsWith("team_"),
+    "Supply the exact Vercel account ID and type.",
+  );
+
+const siteSchema = z
+  .object({
+    mode: z.enum(["existing", "new"]),
+    projectId: z
+      .string()
+      .regex(/^prj_[A-Za-z0-9]+$/)
+      .refine((v) => !/REPLACE/i.test(v))
+      .optional(),
+    projectName,
+    creationApproved: z.boolean().optional(),
+    build: z
+      .array(
+        z
+          .string()
+          .min(1)
+          .refine(
+            (v) => !/myshop|[\n\r\0]/i.test(v),
+            "MyShop must remain local-only.",
+          ),
+      )
+      .min(1)
+      .refine(
+        (v) => v[0] === "pnpm",
+        "Build must be an explicit pnpm argument array.",
+      ),
+    output: z.string(),
+    outputConfig: z
+      .object({
+        version: z.literal(3),
+        routes: z.array(z.unknown()).optional(),
+        overrides: z.record(z.string(), z.unknown()).optional(),
+      })
+      .strict(),
+  })
+  .strict()
+  .refine(
+    (s) =>
+      s.mode === "existing"
+        ? Boolean(s.projectId) && s.creationApproved === undefined
+        : s.projectId === undefined && typeof s.creationApproved === "boolean",
+    "Existing sites require projectId; new sites require creationApproved.",
+  );
+
+const sitesSchema = z
+  .record(
+    z
+      .string()
+      .regex(/^[a-z][a-z0-9-]*$/)
+      .refine((v) => !/myshop/i.test(v), "MyShop is local-only."),
+    siteSchema,
+  )
+  .refine((v) => Object.keys(v).length > 0, "Select at least one static site.");
+
+export const vercelInputSchema = z
+  .object({
+    repository: z
+      .string()
+      .regex(/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/),
+    account: accountSchema,
+    sites: sitesSchema,
+  })
+  .strict();
+export const vercelConfigSchema = vercelInputSchema
+  .extend({
+    version: z.literal(1),
+    mode: z.literal("vercel"),
+    slug: z.string().regex(/^[a-z][a-z0-9-]{0,22}$/),
+    approved: z.boolean(),
+  })
+  .strict();
+export const vercelResponseSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  accountId: z.string().optional(),
+  user: z.object({ id: z.string() }).optional(),
+});
+export type VercelConfig = z.infer<typeof vercelConfigSchema>;
+export type VercelSite = z.infer<typeof siteSchema>;
+export type VercelAccount = z.infer<typeof accountSchema>;
+export type VercelResponse = z.infer<typeof vercelResponseSchema>;
+export type VercelRequest = (
+  method: string,
+  path: string,
+  account: VercelAccount,
+  body?: unknown,
+) => Promise<VercelResponse | null>;
+export type RunProcess = (
+  command: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+) => void | Promise<void>;
+export const terraformConfigSchema = z.object({
+  version: z.literal(1),
+  slug: z.string(),
+  repository: z.string(),
+  approved: z.boolean(),
+  services: z.array(z.string()),
+  workloadIdentityProvider: z.string(),
+  serviceAccount: z.string(),
+});
+export const envPoolSchema = z.record(
+  z.string().regex(/^[A-Z_][A-Z0-9_]*$/),
+  z.string(),
+);

package/src/secrets/assertNewSource.ts

@@ -0,0 +1,40 @@
+import { posix } from "node:path";
+import type { SecretSource } from "./config.js";
+import { secretCommand } from "./secretCommand.js";
+
+// fm's write API can overwrite without --force, so its default is not create-only.
+export const assertNewSource = (source: SecretSource, root: string) => {
+  const listing = secretCommand(
+    "fm",
+    [
+      "file",
+      "ls",
+      posix.dirname(source.path),
+      "--store",
+      source.store,
+      "--json",
+    ],
+    root,
+  );
+
+  let names: string[];
+
+  try {
+    names = listing
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        const entry = JSON.parse(line) as { message?: unknown };
+        if (typeof entry.message !== "string") throw new Error();
+        return entry.message;
+      });
+  } catch {
+    throw new Error("Cannot verify that the new Forum path is unused.");
+  }
+
+  if (names.includes(posix.basename(source.path)))
+    throw new Error(
+      "Forum file already exists; use secrets add to attach it without replacing its contents.",
+    );
+};

package/src/secrets/config.ts

@@ -0,0 +1,91 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { safeTargetPath } from "../safeTargetPath.js";
+
+export const envName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/);
+export const sourceSchema = z
+  .object({
+    name: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    store: z.string().regex(/^[\w-]+\/[\w-]+$/),
+    path: z
+      .string()
+      .startsWith("/")
+      .endsWith(".enc")
+      .refine(
+        (path) =>
+          !/[\r\n\0]/.test(path) &&
+          path
+            .split("/")
+            .slice(1)
+            .every((part) => part && part !== "." && part !== ".."),
+      ),
+    keyEnv: envName,
+    tokenEnv: envName.optional(),
+    snapshot: z
+      .object({
+        file: z.string(),
+        fileId: z.string().min(1),
+        revision: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export const secretsConfigSchema = z
+  .object({
+    version: z.literal(1),
+    repository: z.string().regex(/^[\w.-]+\/[\w.-]+$/),
+    sources: z.array(sourceSchema).min(1),
+    consumers: z
+      .record(
+        z.string(),
+        z.record(
+          z.string().min(1),
+          z.union([envName, z.array(envName).min(1)]),
+        ),
+      )
+      .default({}),
+  })
+  .strict()
+  .superRefine((config, ctx) => {
+    if (
+      new Set(config.sources.map((s) => s.name)).size !== config.sources.length
+    )
+      ctx.addIssue({ code: "custom", message: "Source names must be unique." });
+    if (
+      new Set(config.sources.map((s) => s.keyEnv)).size !==
+      config.sources.length
+    )
+      ctx.addIssue({
+        code: "custom",
+        message: "Each source needs its own key environment name.",
+      });
+    for (const mapping of Object.values(config.consumers))
+      for (const name of Object.keys(mapping))
+        if (
+          !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
+          name !== "pnpm_config_//registry.npmjs.org/:_authToken"
+        )
+          ctx.addIssue({
+            code: "custom",
+            message: "Invalid output environment name.",
+          });
+  });
+export type SecretsConfig = z.infer<typeof secretsConfigSchema>;
+export type SecretSource = z.infer<typeof sourceSchema>;
+
+export const readSecretsConfig = (
+  root: string,
+  file = ".arcnet/secrets.json",
+): SecretsConfig => {
+  try {
+    return secretsConfigSchema.parse(
+      JSON.parse(readFileSync(safeTargetPath(root, file), "utf8")),
+    );
+  } catch {
+    throw new Error(
+      "Missing or invalid secrets configuration (values omitted).",
+    );
+  }
+};

package/src/secrets/createSecretsCommands.ts

@@ -0,0 +1,189 @@
+import { Command } from "commander";
+import { realpathSync } from "node:fs";
+import { readSecretsConfig } from "./config.js";
+import { loadSecrets } from "./loadSecrets.js";
+import { provisionSource, type ProvisionOptions } from "./provisionSource.js";
+import { runWithSecrets } from "./runWithSecrets.js";
+import { selectSecrets } from "./selectSecrets.js";
+import { syncSecrets } from "./syncSecrets.js";
+import { writeSecretsWorkflow } from "./writeSecretsWorkflow.js";
+
+export const createSecretsCommands = (
+  cli: Command,
+  output: (value: unknown) => void,
+) => {
+  const env = cli
+    .command("env")
+    .description(
+      "Load ordered encrypted Forum sources and select environment values.",
+    );
+
+  for (const action of ["check", "export", "run"] as const) {
+    const command = env
+      .command(action)
+      .description(
+        {
+          check: "Validate decryption and mappings; report key names only.",
+          export:
+            "Write selected plaintext JSON to stdout for an explicit pipeline.",
+          run: "Run a command with selected keys only; withhold child output.",
+        }[action],
+      )
+      .option(
+        "--config <file>",
+        "Secrets source configuration",
+        ".arcnet/secrets.json",
+      )
+      .option("--consumer <name>", "Named mapping in the secrets configuration")
+      .option(
+        "--live",
+        "Fetch current ciphertext through the installed fm CLI instead of snapshots",
+      );
+
+    if (action === "run")
+      command.argument("<command...>", "Executable and arguments after --");
+    command.action(async (...args: unknown[]) => {
+      const options = command.opts<{
+        config: string;
+        consumer?: string;
+        live?: boolean;
+      }>();
+
+      const root = realpathSync(cli.opts().root);
+      const config = readSecretsConfig(root, options.config);
+      if (
+        process.env.GITHUB_ACTIONS === "true" &&
+        (process.env.GITHUB_REPOSITORY !== config.repository ||
+          process.env.GITHUB_REF !== "refs/heads/main")
+      )
+        throw new Error(
+          "Secrets commands in CI require the configured repository main branch.",
+        );
+      if (action !== "check" && !options.consumer)
+        throw new Error("Choose --consumer to explicitly select output keys.");
+      const values = await loadSecrets(config, root, process.env, options.live);
+
+      const names = options.consumer
+        ? [options.consumer]
+        : Object.keys(config.consumers);
+
+      const selected = Object.fromEntries(
+        names.map((name) => [name, selectSecrets(values, config, name)]),
+      );
+
+      if (action === "export")
+        process.stdout.write(
+          JSON.stringify(selected[options.consumer!]) + "\n",
+        );
+      else if (action === "run")
+        output(
+          runWithSecrets(
+            args[0] as string[],
+            selected[options.consumer!]!,
+            root,
+          ),
+        );
+      else
+        output({
+          operation: "env.check",
+          status: "passed",
+          sources: config.sources.map((source) => source.name),
+          consumers: Object.fromEntries(
+            Object.entries(selected).map(([name, value]) => [
+              name,
+              Object.keys(value),
+            ]),
+          ),
+          message:
+            "Decryption, merge and required-key checks passed; provider authorization was not tested.",
+        });
+    });
+  }
+
+  const secrets = cli
+    .command("secrets")
+    .description(
+      "Attach Forum files, provision GitHub keys and refresh encrypted snapshots.",
+    );
+
+  for (const mode of ["add", "init"] as const) {
+    const command = secrets
+      .command(mode)
+      .description(
+        mode === "add"
+          ? "Attach an existing Forum file and provision its CI key."
+          : "Create a Forum secrets file, prompt for your password and provision its CI key.",
+      )
+      .requiredOption(
+        "--name <name>",
+        "Unique source name; sources merge in installation order",
+      )
+      .requiredOption("--store <workspace/store>", "Forum store")
+      .requiredOption("--path <path>", "Encrypted file path in Forum")
+      .requiredOption(
+        "--key-env <name>",
+        "GitHub repository secret / environment variable for this file's key",
+      )
+      .requiredOption(
+        "--repository <owner/repo>",
+        "GitHub repository receiving the key",
+      )
+      .option(
+        "--config <file>",
+        "Secrets source configuration",
+        ".arcnet/secrets.json",
+      );
+
+    if (mode === "add")
+      command.option(
+        "--existing-key",
+        "Reuse an existing GitHub secret without creating a recipient",
+      );
+    else
+      command.option(
+        "--input <file>",
+        "Initial plaintext JSON file; defaults to an empty object",
+      );
+    command.action(async () =>
+      output(
+        await provisionSource(
+          mode,
+          {
+            ...command.opts<ProvisionOptions>(),
+            noninteractive: cli.opts().noninteractive,
+          },
+          realpathSync(cli.opts().root),
+          command.opts().config,
+        ),
+      ),
+    );
+  }
+
+  secrets
+    .command("sync")
+    .description(
+      "Refresh encrypted snapshots from Forum and regenerate validation CI; no decryption.",
+    )
+    .option(
+      "--config <file>",
+      "Secrets source configuration",
+      ".arcnet/secrets.json",
+    )
+    .action((options: { config: string }) => {
+      const root = realpathSync(cli.opts().root);
+
+      const result = syncSecrets(
+        readSecretsConfig(root, options.config),
+        root,
+        options.config,
+      );
+
+      writeSecretsWorkflow(
+        readSecretsConfig(root, options.config),
+        root,
+        options.config,
+      );
+
+      output(result);
+    });
+};

package/src/secrets/loadSecrets.ts

@@ -0,0 +1,53 @@
+import { decryptForumEncryptedFileText } from "@mp-lb/forum-secrets";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { safeTargetPath } from "../safeTargetPath.js";
+import type { SecretsConfig } from "./config.js";
+import { readRemoteSource } from "./readRemoteSource.js";
+
+export const loadSecrets = async (
+  config: SecretsConfig,
+  root: string,
+  environment = process.env,
+  live = false,
+) => {
+  let values: Record<string, unknown> = {};
+
+  for (const source of config.sources) {
+    const key = environment[source.keyEnv];
+    if (!key)
+      throw new Error(`Missing decryption credential: ${source.keyEnv}.`);
+
+    try {
+      const text =
+        !live && source.snapshot
+          ? readFileSync(safeTargetPath(root, source.snapshot.file), "utf8")
+          : readRemoteSource(source, root, environment).text;
+
+      if (
+        !live &&
+        source.snapshot &&
+        createHash("sha256").update(text).digest("hex") !==
+          source.snapshot.sha256
+      )
+        throw new Error("Snapshot integrity mismatch");
+
+      const decoded: unknown = JSON.parse(
+        await decryptForumEncryptedFileText({
+          encryptedText: text,
+          recipientSecret: key,
+        }),
+      );
+
+      if (!decoded || Array.isArray(decoded) || typeof decoded !== "object")
+        throw new Error("Not an object");
+      values = { ...values, ...decoded };
+    } catch {
+      throw new Error(
+        `Source ${source.name} failed to load or decrypt; check its key and snapshot integrity (values omitted).`,
+      );
+    }
+  }
+
+  return values;
+};

package/src/secrets/promptPassword.ts

@@ -0,0 +1,46 @@
+export const promptPassword = async (
+  noninteractive = false,
+): Promise<string> => {
+  if (process.env.DOCTRINE_ENCRYPTION_PASSWORD)
+    return process.env.DOCTRINE_ENCRYPTION_PASSWORD;
+  if (noninteractive || !process.stdin.isTTY || !process.stderr.isTTY)
+    throw new Error(
+      "Run this command in your terminal to enter the Forum encryption password, or set DOCTRINE_ENCRYPTION_PASSWORD.",
+    );
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const input = process.stdin;
+    const wasRaw = input.isRaw;
+
+    const finish = (cancel = false) => {
+      input.off("data", read);
+      input.setRawMode(wasRaw);
+      input.pause();
+      process.stderr.write("\n");
+      if (cancel || !value) reject(new Error("Password entry cancelled."));
+      else resolve(value);
+    };
+
+    const read = (chunk: Buffer) => {
+      for (const character of chunk.toString("utf8")) {
+        if (character === "\u0003") {
+          finish(true);
+          return;
+        }
+
+        if (character === "\r" || character === "\n") {
+          finish();
+          return;
+        }
+
+        if (character === "\u007f") value = [...value].slice(0, -1).join("");
+        else value += character;
+      }
+    };
+
+    process.stderr.write("Forum encryption password: ");
+    input.setRawMode(true);
+    input.on("data", read);
+    input.resume();
+  });
+};