@lukoweb/apitogo 0.2.22 → 0.2.24

package/src/config/v2/ledger.ts

@@ -1,235 +1,235 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { ApitogoError } from "../../lib/util/invariant.js";
-import type { StatePaths } from "./paths.js";
-
-/** Version of the `state.json` format this build reads and writes. A newer file is refused, never overwritten. */
-export const LEDGER_VERSION = 1;
-
-export type StepStatus = "running" | "succeeded" | "failed";
-
-/** One step of one service, for example `portal` / `build`. */
-export type StepRecord = {
-  status: StepStatus;
-  /** Hash of the inputs the step ran with. An equal hash means the result is still valid. */
-  hash?: string;
-  startedAt: string;
-  finishedAt?: string;
-  /** Why the step failed. */
-  error?: string;
-  /** Public facts the step produced, such as a deployed URL. */
-  output?: Record<string, string>;
-};
-
-export type Ledger = {
-  version: typeof LEDGER_VERSION;
-  services: Record<string, { steps: Record<string, StepRecord> }>;
-};
-
-export class LedgerError extends ApitogoError {
-  constructor(
-    public readonly code: "LEDGER_CORRUPT" | "LEDGER_VERSION_UNSUPPORTED",
-    message: string,
-    developerHint?: string,
-  ) {
-    super(message, { developerHint, title: "Cannot read the project state" });
-    this.name = "LedgerError";
-  }
-}
-
-export const emptyLedger = (): Ledger => ({
-  version: LEDGER_VERSION,
-  services: {},
-});
-
-/** Reads `state.json`. A missing file is an empty ledger. A corrupt or newer file raises a {@link LedgerError}. */
-export async function readLedger(
-  state: Pick<StatePaths, "file">,
-): Promise<Ledger> {
-  let text: string;
-  try {
-    text = await readFile(state.file, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT")
-      return emptyLedger();
-    throw error;
-  }
-
-  let raw: unknown;
-  try {
-    raw = JSON.parse(text);
-  } catch {
-    throw corrupt(state.file, "is not valid JSON");
-  }
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    throw corrupt(state.file, "is not an object");
-  }
-  const { version, services } = raw as Record<string, unknown>;
-  if (typeof version !== "number") throw corrupt(state.file, "has no version");
-  if (version > LEDGER_VERSION) {
-    throw new LedgerError(
-      "LEDGER_VERSION_UNSUPPORTED",
-      `${state.file} has version ${version} but this CLI supports ${LEDGER_VERSION}.`,
-      "Upgrade @lukoweb/apitogo.",
-    );
-  }
-  if (version !== LEDGER_VERSION)
-    throw corrupt(state.file, `has unknown version ${version}`);
-  if (
-    typeof services !== "object" ||
-    services === null ||
-    Array.isArray(services)
-  ) {
-    throw corrupt(state.file, "has no services object");
-  }
-  return { version: LEDGER_VERSION, services: services as Ledger["services"] };
-}
-
-function corrupt(file: string, why: string): LedgerError {
-  return new LedgerError(
-    "LEDGER_CORRUPT",
-    `${file} ${why}.`,
-    "It only holds regenerable state: delete it and run the command again.",
-  );
-}
-
-/** Replaces `state.json` atomically, so a crash never leaves a half-written file. */
-export async function writeLedger(
-  state: Pick<StatePaths, "file">,
-  ledger: Ledger,
-): Promise<void> {
-  await mkdir(path.dirname(state.file), { recursive: true });
-  const temporary = `${state.file}.${process.pid}.tmp`;
-  try {
-    await writeFile(temporary, `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
-    await rename(temporary, state.file);
-  } catch (error) {
-    await rm(temporary, { force: true });
-    throw error;
-  }
-}
-
-export function stepOf(
-  ledger: Ledger,
-  service: string,
-  step: string,
-): StepRecord | undefined {
-  return ledger.services[service]?.steps[step];
-}
-
-function withStep(
-  ledger: Ledger,
-  service: string,
-  step: string,
-  record: StepRecord,
-): Ledger {
-  return {
-    ...ledger,
-    services: {
-      ...ledger.services,
-      [service]: {
-        steps: { ...ledger.services[service]?.steps, [step]: record },
-      },
-    },
-  };
-}
-
-export type PipelineStep = {
-  name: string;
-  /** Hash of this step's inputs. */
-  hash: () => string | Promise<string>;
-  run: () => Promise<Record<string, string> | undefined | void>;
-  /** Extra proof the previous result still exists (for example the build folder). Defaults to true. */
-  stillValid?: () => Promise<boolean>;
-};
-
-export type StepOutcome = {
-  step: string;
-  skipped: boolean;
-  output?: Record<string, string>;
-};
-
-/**
- * Runs a service's steps in order against the ledger. A step is skipped when it already succeeded with the same
- * hash and nothing before it ran again. A failure is recorded with its message and rethrown; the next run starts
- * at that step, because the steps before it succeeded and are skipped.
- */
-export async function runPipeline(
-  state: Pick<StatePaths, "file">,
-  service: string,
-  steps: readonly PipelineStep[],
-  options: { force?: boolean; now?: () => Date } = {},
-): Promise<StepOutcome[]> {
-  const now = options.now ?? (() => new Date());
-  let ledger = await readLedger(state);
-  const outcomes: StepOutcome[] = [];
-  let upstreamRan = false;
-
-  for (const step of steps) {
-    const hash = await step.hash();
-    const previous = stepOf(ledger, service, step.name);
-    const reusable =
-      !options.force &&
-      !upstreamRan &&
-      previous?.status === "succeeded" &&
-      previous.hash === hash &&
-      (step.stillValid ? await step.stillValid() : true);
-
-    if (reusable) {
-      outcomes.push({
-        step: step.name,
-        skipped: true,
-        output: previous?.output,
-      });
-      continue;
-    }
-
-    upstreamRan = true;
-    const startedAt = now().toISOString();
-    ledger = withStep(ledger, service, step.name, {
-      status: "running",
-      hash,
-      startedAt,
-    });
-    await writeLedger(state, ledger);
-    try {
-      const output = (await step.run()) || undefined;
-      ledger = withStep(ledger, service, step.name, {
-        status: "succeeded",
-        hash,
-        startedAt,
-        finishedAt: now().toISOString(),
-        ...(output ? { output } : {}),
-      });
-      await writeLedger(state, ledger);
-      outcomes.push({ step: step.name, skipped: false, output });
-    } catch (error) {
-      ledger = withStep(ledger, service, step.name, {
-        status: "failed",
-        hash,
-        startedAt,
-        finishedAt: now().toISOString(),
-        error: error instanceof Error ? error.message : String(error),
-      });
-      await writeLedger(state, ledger);
-      throw error;
-    }
-  }
-  return outcomes;
-}
-
-/** Forgets the recorded steps of services that no longer exist on the platform. Other services keep their entries. */
-export async function clearServices(
-  state: Pick<StatePaths, "file">,
-  services: readonly string[],
-): Promise<void> {
-  const ledger = await readLedger(state);
-  const remaining = Object.fromEntries(
-    Object.entries(ledger.services).filter(
-      ([name]) => !services.includes(name),
-    ),
-  );
-  if (Object.keys(remaining).length === Object.keys(ledger.services).length)
-    return;
-  await writeLedger(state, { ...ledger, services: remaining });
-}
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ApitogoError } from "../../lib/util/invariant.js";
+import type { StatePaths } from "./paths.js";
+
+/** Version of the `state.json` format this build reads and writes. A newer file is refused, never overwritten. */
+export const LEDGER_VERSION = 1;
+
+export type StepStatus = "running" | "succeeded" | "failed";
+
+/** One step of one service, for example `portal` / `build`. */
+export type StepRecord = {
+  status: StepStatus;
+  /** Hash of the inputs the step ran with. An equal hash means the result is still valid. */
+  hash?: string;
+  startedAt: string;
+  finishedAt?: string;
+  /** Why the step failed. */
+  error?: string;
+  /** Public facts the step produced, such as a deployed URL. */
+  output?: Record<string, string>;
+};
+
+export type Ledger = {
+  version: typeof LEDGER_VERSION;
+  services: Record<string, { steps: Record<string, StepRecord> }>;
+};
+
+export class LedgerError extends ApitogoError {
+  constructor(
+    public readonly code: "LEDGER_CORRUPT" | "LEDGER_VERSION_UNSUPPORTED",
+    message: string,
+    developerHint?: string,
+  ) {
+    super(message, { developerHint, title: "Cannot read the project state" });
+    this.name = "LedgerError";
+  }
+}
+
+export const emptyLedger = (): Ledger => ({
+  version: LEDGER_VERSION,
+  services: {},
+});
+
+/** Reads `state.json`. A missing file is an empty ledger. A corrupt or newer file raises a {@link LedgerError}. */
+export async function readLedger(
+  state: Pick<StatePaths, "file">,
+): Promise<Ledger> {
+  let text: string;
+  try {
+    text = await readFile(state.file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      return emptyLedger();
+    throw error;
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw corrupt(state.file, "is not valid JSON");
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw corrupt(state.file, "is not an object");
+  }
+  const { version, services } = raw as Record<string, unknown>;
+  if (typeof version !== "number") throw corrupt(state.file, "has no version");
+  if (version > LEDGER_VERSION) {
+    throw new LedgerError(
+      "LEDGER_VERSION_UNSUPPORTED",
+      `${state.file} has version ${version} but this CLI supports ${LEDGER_VERSION}.`,
+      "Upgrade @lukoweb/apitogo.",
+    );
+  }
+  if (version !== LEDGER_VERSION)
+    throw corrupt(state.file, `has unknown version ${version}`);
+  if (
+    typeof services !== "object" ||
+    services === null ||
+    Array.isArray(services)
+  ) {
+    throw corrupt(state.file, "has no services object");
+  }
+  return { version: LEDGER_VERSION, services: services as Ledger["services"] };
+}
+
+function corrupt(file: string, why: string): LedgerError {
+  return new LedgerError(
+    "LEDGER_CORRUPT",
+    `${file} ${why}.`,
+    "It only holds regenerable state: delete it and run the command again.",
+  );
+}
+
+/** Replaces `state.json` atomically, so a crash never leaves a half-written file. */
+export async function writeLedger(
+  state: Pick<StatePaths, "file">,
+  ledger: Ledger,
+): Promise<void> {
+  await mkdir(path.dirname(state.file), { recursive: true });
+  const temporary = `${state.file}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
+    await rename(temporary, state.file);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export function stepOf(
+  ledger: Ledger,
+  service: string,
+  step: string,
+): StepRecord | undefined {
+  return ledger.services[service]?.steps[step];
+}
+
+function withStep(
+  ledger: Ledger,
+  service: string,
+  step: string,
+  record: StepRecord,
+): Ledger {
+  return {
+    ...ledger,
+    services: {
+      ...ledger.services,
+      [service]: {
+        steps: { ...ledger.services[service]?.steps, [step]: record },
+      },
+    },
+  };
+}
+
+export type PipelineStep = {
+  name: string;
+  /** Hash of this step's inputs. */
+  hash: () => string | Promise<string>;
+  run: () => Promise<Record<string, string> | undefined | void>;
+  /** Extra proof the previous result still exists (for example the build folder). Defaults to true. */
+  stillValid?: () => Promise<boolean>;
+};
+
+export type StepOutcome = {
+  step: string;
+  skipped: boolean;
+  output?: Record<string, string>;
+};
+
+/**
+ * Runs a service's steps in order against the ledger. A step is skipped when it already succeeded with the same
+ * hash and nothing before it ran again. A failure is recorded with its message and rethrown; the next run starts
+ * at that step, because the steps before it succeeded and are skipped.
+ */
+export async function runPipeline(
+  state: Pick<StatePaths, "file">,
+  service: string,
+  steps: readonly PipelineStep[],
+  options: { force?: boolean; now?: () => Date } = {},
+): Promise<StepOutcome[]> {
+  const now = options.now ?? (() => new Date());
+  let ledger = await readLedger(state);
+  const outcomes: StepOutcome[] = [];
+  let upstreamRan = false;
+
+  for (const step of steps) {
+    const hash = await step.hash();
+    const previous = stepOf(ledger, service, step.name);
+    const reusable =
+      !options.force &&
+      !upstreamRan &&
+      previous?.status === "succeeded" &&
+      previous.hash === hash &&
+      (step.stillValid ? await step.stillValid() : true);
+
+    if (reusable) {
+      outcomes.push({
+        step: step.name,
+        skipped: true,
+        output: previous?.output,
+      });
+      continue;
+    }
+
+    upstreamRan = true;
+    const startedAt = now().toISOString();
+    ledger = withStep(ledger, service, step.name, {
+      status: "running",
+      hash,
+      startedAt,
+    });
+    await writeLedger(state, ledger);
+    try {
+      const output = (await step.run()) || undefined;
+      ledger = withStep(ledger, service, step.name, {
+        status: "succeeded",
+        hash,
+        startedAt,
+        finishedAt: now().toISOString(),
+        ...(output ? { output } : {}),
+      });
+      await writeLedger(state, ledger);
+      outcomes.push({ step: step.name, skipped: false, output });
+    } catch (error) {
+      ledger = withStep(ledger, service, step.name, {
+        status: "failed",
+        hash,
+        startedAt,
+        finishedAt: now().toISOString(),
+        error: error instanceof Error ? error.message : String(error),
+      });
+      await writeLedger(state, ledger);
+      throw error;
+    }
+  }
+  return outcomes;
+}
+
+/** Forgets the recorded steps of services that no longer exist on the platform. Other services keep their entries. */
+export async function clearServices(
+  state: Pick<StatePaths, "file">,
+  services: readonly string[],
+): Promise<void> {
+  const ledger = await readLedger(state);
+  const remaining = Object.fromEntries(
+    Object.entries(ledger.services).filter(
+      ([name]) => !services.includes(name),
+    ),
+  );
+  if (Object.keys(remaining).length === Object.keys(ledger.services).length)
+    return;
+  await writeLedger(state, { ...ledger, services: remaining });
+}

package/src/config/v2/link-directory.ts

@@ -0,0 +1,34 @@
+import { symlink } from "node:fs/promises";
+
+type SymlinkFn = (
+  target: string,
+  path: string,
+  type?: "dir" | "file" | "junction",
+) => Promise<void>;
+
+/**
+ * Links `link` to the directory `target`. On Windows a directory symlink needs a privilege most accounts do not
+ * have (Developer Mode or an elevated shell) and fails with EPERM; a junction needs none and behaves the same for
+ * reading, so it is used then. Any other failure, and EPERM on another system, is not hidden.
+ */
+export async function linkDirectory(
+  target: string,
+  link: string,
+  options: { symlinkFn?: SymlinkFn; platform?: NodeJS.Platform } = {},
+): Promise<"symlink" | "junction"> {
+  const create = options.symlinkFn ?? symlink;
+  const platform = options.platform ?? process.platform;
+  try {
+    await create(target, link, "dir");
+    return "symlink";
+  } catch (error) {
+    if (
+      platform !== "win32" ||
+      (error as NodeJS.ErrnoException).code !== "EPERM"
+    )
+      throw error;
+    // A junction takes an absolute target.
+    await create(target, link, "junction");
+    return "junction";
+  }
+}

package/src/config/v2/load.ts

@@ -1,70 +1,70 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import path from "node:path";
-import { APITOGO_CONFIG_FILENAME } from "../apitogo-config-core.js";
-import { ConfigError } from "./errors.js";
-import { parseConfigV2 } from "./parse.js";
-import { type ResolvedConfigV2, resolveConfigV2 } from "./resolve.js";
-import type { ConfigV2 } from "./schema.js";
-
-export type LoadedConfigV2 = {
-  config: ConfigV2;
-  resolved: ResolvedConfigV2;
-};
-
-/** `JSON.parse` failures carry a position in different shapes across Node versions; turn it into line and column. */
-function describeJsonError(error: unknown, text: string): string {
-  const message = error instanceof Error ? error.message : String(error);
-  const lineColumn = /line (\d+) column (\d+)/.exec(message);
-  if (lineColumn) return `${message}`;
-
-  const position = /position (\d+)/.exec(message);
-  if (!position) return message;
-
-  const offset = Number(position[1]);
-  const before = text.slice(0, offset);
-  const line = before.split("\n").length;
-  const column = offset - before.lastIndexOf("\n");
-  return `${message} (line ${line} column ${column})`;
-}
-
-/**
- * Reads, validates and resolves a v2 config. `pathOrDir` is either the config file or the directory that
- * contains `apitogo.config.json`. Invalid JSON, unknown keys, inline secrets and every other schema problem
- * raise a {@link ConfigError}; nothing is silently dropped.
- */
-export function loadConfigV2(pathOrDir: string): LoadedConfigV2 {
-  const resolvedPath = path.resolve(pathOrDir);
-  const configPath =
-    existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()
-      ? path.join(resolvedPath, APITOGO_CONFIG_FILENAME)
-      : resolvedPath;
-
-  if (!existsSync(configPath)) {
-    throw new ConfigError(path.basename(configPath), [
-      {
-        code: "CONFIG_NOT_FOUND",
-        path: "",
-        message: `No config file at ${configPath}.`,
-        hint: "Run `apitogo init` to create one.",
-      },
-    ]);
-  }
-
-  const text = readFileSync(configPath, "utf8");
-  let raw: unknown;
-  try {
-    raw = JSON.parse(text);
-  } catch (error) {
-    throw new ConfigError(path.basename(configPath), [
-      {
-        code: "CONFIG_INVALID_JSON",
-        path: "",
-        message: describeJsonError(error, text),
-        hint: "Fix the JSON syntax; comments and trailing commas are not allowed.",
-      },
-    ]);
-  }
-
-  const config = parseConfigV2(raw, path.basename(configPath));
-  return { config, resolved: resolveConfigV2(config, configPath) };
-}
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { APITOGO_CONFIG_FILENAME } from "../apitogo-config-core.js";
+import { ConfigError } from "./errors.js";
+import { parseConfigV2 } from "./parse.js";
+import { type ResolvedConfigV2, resolveConfigV2 } from "./resolve.js";
+import type { ConfigV2 } from "./schema.js";
+
+export type LoadedConfigV2 = {
+  config: ConfigV2;
+  resolved: ResolvedConfigV2;
+};
+
+/** `JSON.parse` failures carry a position in different shapes across Node versions; turn it into line and column. */
+function describeJsonError(error: unknown, text: string): string {
+  const message = error instanceof Error ? error.message : String(error);
+  const lineColumn = /line (\d+) column (\d+)/.exec(message);
+  if (lineColumn) return `${message}`;
+
+  const position = /position (\d+)/.exec(message);
+  if (!position) return message;
+
+  const offset = Number(position[1]);
+  const before = text.slice(0, offset);
+  const line = before.split("\n").length;
+  const column = offset - before.lastIndexOf("\n");
+  return `${message} (line ${line} column ${column})`;
+}
+
+/**
+ * Reads, validates and resolves a v2 config. `pathOrDir` is either the config file or the directory that
+ * contains `apitogo.config.json`. Invalid JSON, unknown keys, inline secrets and every other schema problem
+ * raise a {@link ConfigError}; nothing is silently dropped.
+ */
+export function loadConfigV2(pathOrDir: string): LoadedConfigV2 {
+  const resolvedPath = path.resolve(pathOrDir);
+  const configPath =
+    existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()
+      ? path.join(resolvedPath, APITOGO_CONFIG_FILENAME)
+      : resolvedPath;
+
+  if (!existsSync(configPath)) {
+    throw new ConfigError(path.basename(configPath), [
+      {
+        code: "CONFIG_NOT_FOUND",
+        path: "",
+        message: `No config file at ${configPath}.`,
+        hint: "Run `apitogo init` to create one.",
+      },
+    ]);
+  }
+
+  const text = readFileSync(configPath, "utf8");
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new ConfigError(path.basename(configPath), [
+      {
+        code: "CONFIG_INVALID_JSON",
+        path: "",
+        message: describeJsonError(error, text),
+        hint: "Fix the JSON syntax; comments and trailing commas are not allowed.",
+      },
+    ]);
+  }
+
+  const config = parseConfigV2(raw, path.basename(configPath));
+  return { config, resolved: resolveConfigV2(config, configPath) };
+}