@lukoweb/apitogo 0.2.30 → 0.2.34

package/src/config/v2/ledger.ts

@@ -1,235 +1,242 @@
-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.
+ * When no service is left the file is deleted: an empty ledger is the same as a missing one.
+ */
+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;
+  if (Object.keys(remaining).length === 0) {
+    await rm(state.file, { force: true });
+    return;
+  }
+  await writeLedger(state, { ...ledger, services: remaining });
+}

package/src/config/v2/resolve.ts

@@ -4,11 +4,19 @@ import type { ConfigV2, Layout } from "./schema.js";
 
 export { layoutRoot };
 
-/** A path relative to the config file, made absolute. A leading `!` (negated glob) is preserved. */
+/**
+ * A glob is written with forward slashes on every system: the glob library reads a backslash as an escape, so a Windows
+ * path such as `C:\site\portal\pages\**\*.md` matches nothing.
+ */
+export function toGlobPath(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+/** A glob relative to the config file, made absolute. A leading `!` (negated glob) is preserved. */
 function fromConfig(configDir: string, value: string): string {
   return value.startsWith("!")
-    ? `!${path.resolve(configDir, value.slice(1))}`
-    : path.resolve(configDir, value);
+    ? `!${toGlobPath(path.resolve(configDir, value.slice(1)))}`
+    : toGlobPath(path.resolve(configDir, value));
 }
 
 export type ResolvedPortal = {
@@ -126,7 +134,7 @@ export function resolveConfigV2(
             ? []
             : portal.docs?.content
               ? portal.docs.content.map((glob) => fromConfig(configDir, glob))
-              : [path.join(dir, "pages", "**", "*.{md,mdx}")],
+              : [toGlobPath(path.join(dir, "pages", "**", "*.{md,mdx}"))],
         url: portal.docs?.url,
       },
       console: { enabled: portal.console?.enabled ?? true },