skur-manifest 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The Manifest is an app's factory-facing contract: the only thing the factory
+ * needs to read in order to host an app. This module is deep and pure — it turns
+ * manifest *text* into a typed {@link Manifest} or a structured {@link ParseError},
+ * and never throws. Everything downstream (CLI scaffold, builder, orchestrator,
+ * proxy) reads the parsed structure, never the raw TOML.
+ */
+export interface ScheduledJob {
+    name: string;
+    cron: string;
+    path: string;
+}
+export interface Manifest {
+    /** App slug — used as subdomain and as the key everywhere else. */
+    name: string;
+    /** Human-readable name shown in the admin UI. */
+    display_name: string;
+    port: number;
+    db_name: string;
+    /** Names (not values) of the env vars the factory must inject before start. */
+    required_env: string[];
+    scheduled_jobs: ScheduledJob[];
+    /** Path prefixes that bypass SSO (webhook targets). */
+    public_paths: string[];
+    /** Auto-derived from `interAppEndpoint` exports at build time; empty at scaffold. */
+    inter_app_api: string[];
+    /** One-time seed for the access list. */
+    initial_admins: string[];
+    /** Where the factory's liveness probe hits the app. */
+    healthcheck_path: string;
+    /**
+     * Docker build context for this app. `"app"` (default) — the app's own folder
+     * is the context (self-contained: deps live only in that folder). `"repo"` —
+     * the apps-repo root is the context, which SDK apps need so npm workspaces
+     * resolve the pinned `skur-sdk`. The TypeScript scaffold sets `"repo"`.
+     */
+    build: {
+        context: "app" | "repo";
+    };
+    /**
+     * Shell command to run in a one-shot container of the NEW image before the
+     * version swap. The factory injects `DATABASE_URL` and the app's secrets.
+     * Non-zero exit aborts the swap — the old version keeps serving (ADR-0010).
+     * Absent means no migration step (e.g. a stateless app or schema-at-startup).
+     */
+    migrate?: string;
+}
+export interface ManifestIssue {
+    /** Dotted path to the offending field, e.g. `scheduled_jobs.0.cron`. */
+    path: string;
+    message: string;
+}
+export type ParseError = {
+    kind: "toml";
+    message: string;
+} | {
+    kind: "schema";
+    message: string;
+    issues: ManifestIssue[];
+};
+export type ParseResult = {
+    ok: true;
+    manifest: Manifest;
+} | {
+    ok: false;
+    error: ParseError;
+};
+/** Legal app slug: a valid subdomain label and Postgres-safe base. The single
+ * source of truth for "what is a valid app name" — the CLI scaffold imports it. */
+export declare const APP_NAME: RegExp;
+/**
+ * Write the registry-derived `inter_app_api` path list back into an app's manifest
+ * TOML, rewriting ONLY that one field and leaving the rest of the file
+ * byte-identical — comments, key order, whitespace, and every other field
+ * untouched. This is a surgical text edit, NOT a parse-and-re-serialize (which
+ * would clobber the comments and formatting an author put there).
+ *
+ * `inter_app_api` is auto-derived (the manifest must not drift from the code), so
+ * this is the build step's mechanism for persisting the derived list. If the field
+ * is absent it is appended; if present (inline or multi-line) its value is replaced
+ * in place.
+ *
+ * Pure: text + list in, new text out. It does not read or write files; the build
+ * step owns the I/O. It does not re-validate — the writer only ever emits a valid
+ * string array, and `Manifest.parse` remains the gate everything else reads through.
+ */
+export declare function writeInterAppApi(manifestText: string, paths: string[]): string;
+export declare const Manifest: {
+    /**
+     * Parse manifest text. Returns `{ ok: true, manifest }` on success or
+     * `{ ok: false, error }` describing either a TOML syntax failure or a list of
+     * schema violations. Never throws.
+     */
+    parse(text: string): ParseResult;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,YAAY,EAAE,CAAC;IAC/B,uDAAuD;IACvD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,qFAAqF;IACrF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,yCAAyC;IACzC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,KAAK,EAAE;QAAE,OAAO,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC;IACnC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAEjE,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAErC;mFACmF;AACnF,eAAO,MAAM,QAAQ,QAAsB,CAAC;AAmF5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAwB9E;AAED,eAAO,MAAM,QAAQ;IACnB;;;;OAIG;gBACS,MAAM,GAAG,WAAW;CAuBjC,CAAC"}

package/dist/index.js

@@ -0,0 +1,144 @@
+import { parse as parseToml, TomlError } from "smol-toml";
+import { z } from "zod";
+/** Legal app slug: a valid subdomain label and Postgres-safe base. The single
+ * source of truth for "what is a valid app name" — the CLI scaffold imports it. */
+export const APP_NAME = /^[a-z][a-z0-9-]*$/;
+const DB_NAME = /^[a-z][a-z0-9_]*$/;
+const path = (field) => z.string().startsWith("/", `${field} must start with "/"`);
+const scheduledJob = z
+    .object({
+    name: z.string().min(1),
+    cron: z.string().min(1),
+    path: path("scheduled job path"),
+})
+    .strict();
+const manifestSchema = z
+    .object({
+    name: z
+        .string()
+        .regex(APP_NAME, "name must be lowercase letters, digits, and hyphens"),
+    display_name: z.string().min(1),
+    port: z
+        .number()
+        .int("port must be an integer")
+        .gte(1, "port must be between 1 and 65535")
+        .lte(65535, "port must be between 1 and 65535"),
+    db_name: z
+        .string()
+        .regex(DB_NAME, "db_name must be a valid Postgres identifier"),
+    required_env: z.array(z.string().min(1)).default([]),
+    scheduled_jobs: z.array(scheduledJob).default([]),
+    public_paths: z.array(path("public path")).default([]),
+    inter_app_api: z
+        .array(path("inter-app path"))
+        .default([])
+        .superRefine((paths, ctx) => {
+        const seen = new Set();
+        paths.forEach((p, i) => {
+            if (seen.has(p)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [i],
+                    message: `duplicate inter_app_api path "${p}"`,
+                });
+            }
+            seen.add(p);
+        });
+    }),
+    initial_admins: z.array(z.string().min(1)).default([]),
+    healthcheck_path: path("healthcheck_path").default("/healthz"),
+    build: z
+        .object({
+        context: z.enum(["app", "repo"]),
+    })
+        .strict()
+        .default({ context: "app" }),
+    migrate: z.string().min(1).optional(),
+})
+    .strict();
+function toIssues(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.join("."),
+        message: issue.message,
+    }));
+}
+/**
+ * Render a TOML string array value, e.g. `["/a", "/b"]`. Single source of truth
+ * for how the field-writer formats the derived list (always inline — the lists are
+ * short, and inline keeps the surrounding file's shape stable).
+ */
+function renderStringArray(values) {
+    return `[${values.map((v) => JSON.stringify(v)).join(", ")}]`;
+}
+/**
+ * Matches a top-level `inter_app_api = [ ... ]` assignment, inline OR multi-line.
+ * Anchored to a line start (after optional indentation) so a same-named key inside
+ * a `[[table]]` block or a comment can't be hit. `[\s\S]*?` spans newlines for the
+ * multi-line array form; non-greedy so it stops at the FIRST closing bracket.
+ */
+const INTER_APP_API_ASSIGNMENT = /^([ \t]*)inter_app_api[ \t]*=[ \t]*\[[\s\S]*?\]/m;
+/**
+ * Write the registry-derived `inter_app_api` path list back into an app's manifest
+ * TOML, rewriting ONLY that one field and leaving the rest of the file
+ * byte-identical — comments, key order, whitespace, and every other field
+ * untouched. This is a surgical text edit, NOT a parse-and-re-serialize (which
+ * would clobber the comments and formatting an author put there).
+ *
+ * `inter_app_api` is auto-derived (the manifest must not drift from the code), so
+ * this is the build step's mechanism for persisting the derived list. If the field
+ * is absent it is appended; if present (inline or multi-line) its value is replaced
+ * in place.
+ *
+ * Pure: text + list in, new text out. It does not read or write files; the build
+ * step owns the I/O. It does not re-validate — the writer only ever emits a valid
+ * string array, and `Manifest.parse` remains the gate everything else reads through.
+ */
+export function writeInterAppApi(manifestText, paths) {
+    const rendered = `inter_app_api = ${renderStringArray(paths)}`;
+    if (INTER_APP_API_ASSIGNMENT.test(manifestText)) {
+        // Replace the existing assignment, preserving its original indentation.
+        return manifestText.replace(INTER_APP_API_ASSIGNMENT, (_match, indent) => `${indent}${rendered}`);
+    }
+    // Absent: append it before the first `[[table]]`/`[table]` section (top-level
+    // keys must precede tables in TOML), or at the end if there are none.
+    const tableHeader = /^[ \t]*\[/m;
+    const match = tableHeader.exec(manifestText);
+    if (match) {
+        const at = match.index;
+        const before = manifestText.slice(0, at).replace(/\n*$/, "");
+        const after = manifestText.slice(at);
+        return `${before}\n${rendered}\n\n${after}`;
+    }
+    const trimmed = manifestText.replace(/\n*$/, "");
+    return `${trimmed}\n${rendered}\n`;
+}
+export const Manifest = {
+    /**
+     * Parse manifest text. Returns `{ ok: true, manifest }` on success or
+     * `{ ok: false, error }` describing either a TOML syntax failure or a list of
+     * schema violations. Never throws.
+     */
+    parse(text) {
+        let raw;
+        try {
+            raw = parseToml(text);
+        }
+        catch (err) {
+            const message = err instanceof TomlError ? err.message : String(err);
+            return { ok: false, error: { kind: "toml", message } };
+        }
+        const result = manifestSchema.safeParse(raw);
+        if (!result.success) {
+            return {
+                ok: false,
+                error: {
+                    kind: "schema",
+                    message: "manifest failed validation",
+                    issues: toIssues(result.error),
+                },
+            };
+        }
+        return { ok: true, manifest: result.data };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "skur-manifest",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Parses and validates an app's manifest file. Deep and pure: text in, typed Manifest or structured error out.",
+  "publishConfig":{"access": "public"},
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "smol-toml": "^1.3.1",
+    "zod": "^3.24.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,222 @@
+import { parse as parseToml, TomlError } from "smol-toml";
+import { z } from "zod";
+
+/**
+ * The Manifest is an app's factory-facing contract: the only thing the factory
+ * needs to read in order to host an app. This module is deep and pure — it turns
+ * manifest *text* into a typed {@link Manifest} or a structured {@link ParseError},
+ * and never throws. Everything downstream (CLI scaffold, builder, orchestrator,
+ * proxy) reads the parsed structure, never the raw TOML.
+ */
+
+export interface ScheduledJob {
+  name: string;
+  cron: string;
+  path: string;
+}
+
+export interface Manifest {
+  /** App slug — used as subdomain and as the key everywhere else. */
+  name: string;
+  /** Human-readable name shown in the admin UI. */
+  display_name: string;
+  port: number;
+  db_name: string;
+  /** Names (not values) of the env vars the factory must inject before start. */
+  required_env: string[];
+  scheduled_jobs: ScheduledJob[];
+  /** Path prefixes that bypass SSO (webhook targets). */
+  public_paths: string[];
+  /** Auto-derived from `interAppEndpoint` exports at build time; empty at scaffold. */
+  inter_app_api: string[];
+  /** One-time seed for the access list. */
+  initial_admins: string[];
+  /** Where the factory's liveness probe hits the app. */
+  healthcheck_path: string;
+  /**
+   * Docker build context for this app. `"app"` (default) — the app's own folder
+   * is the context (self-contained: deps live only in that folder). `"repo"` —
+   * the apps-repo root is the context, which SDK apps need so npm workspaces
+   * resolve the pinned `skur-sdk`. The TypeScript scaffold sets `"repo"`.
+   */
+  build: { context: "app" | "repo" };
+  /**
+   * Shell command to run in a one-shot container of the NEW image before the
+   * version swap. The factory injects `DATABASE_URL` and the app's secrets.
+   * Non-zero exit aborts the swap — the old version keeps serving (ADR-0010).
+   * Absent means no migration step (e.g. a stateless app or schema-at-startup).
+   */
+  migrate?: string;
+}
+
+export interface ManifestIssue {
+  /** Dotted path to the offending field, e.g. `scheduled_jobs.0.cron`. */
+  path: string;
+  message: string;
+}
+
+export type ParseError =
+  | { kind: "toml"; message: string }
+  | { kind: "schema"; message: string; issues: ManifestIssue[] };
+
+export type ParseResult =
+  | { ok: true; manifest: Manifest }
+  | { ok: false; error: ParseError };
+
+/** Legal app slug: a valid subdomain label and Postgres-safe base. The single
+ * source of truth for "what is a valid app name" — the CLI scaffold imports it. */
+export const APP_NAME = /^[a-z][a-z0-9-]*$/;
+const DB_NAME = /^[a-z][a-z0-9_]*$/;
+
+const path = (field: string) =>
+  z.string().startsWith("/", `${field} must start with "/"`);
+
+const scheduledJob = z
+  .object({
+    name: z.string().min(1),
+    cron: z.string().min(1),
+    path: path("scheduled job path"),
+  })
+  .strict();
+
+const manifestSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(APP_NAME, "name must be lowercase letters, digits, and hyphens"),
+    display_name: z.string().min(1),
+    port: z
+      .number()
+      .int("port must be an integer")
+      .gte(1, "port must be between 1 and 65535")
+      .lte(65535, "port must be between 1 and 65535"),
+    db_name: z
+      .string()
+      .regex(DB_NAME, "db_name must be a valid Postgres identifier"),
+    required_env: z.array(z.string().min(1)).default([]),
+    scheduled_jobs: z.array(scheduledJob).default([]),
+    public_paths: z.array(path("public path")).default([]),
+    inter_app_api: z
+      .array(path("inter-app path"))
+      .default([])
+      .superRefine((paths, ctx) => {
+        const seen = new Set<string>();
+        paths.forEach((p, i) => {
+          if (seen.has(p)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: [i],
+              message: `duplicate inter_app_api path "${p}"`,
+            });
+          }
+          seen.add(p);
+        });
+      }),
+    initial_admins: z.array(z.string().min(1)).default([]),
+    healthcheck_path: path("healthcheck_path").default("/healthz"),
+    build: z
+      .object({
+        context: z.enum(["app", "repo"]),
+      })
+      .strict()
+      .default({ context: "app" }),
+    migrate: z.string().min(1).optional(),
+  })
+  .strict();
+
+function toIssues(error: z.ZodError): ManifestIssue[] {
+  return error.issues.map((issue) => ({
+    path: issue.path.join("."),
+    message: issue.message,
+  }));
+}
+
+/**
+ * Render a TOML string array value, e.g. `["/a", "/b"]`. Single source of truth
+ * for how the field-writer formats the derived list (always inline — the lists are
+ * short, and inline keeps the surrounding file's shape stable).
+ */
+function renderStringArray(values: string[]): string {
+  return `[${values.map((v) => JSON.stringify(v)).join(", ")}]`;
+}
+
+/**
+ * Matches a top-level `inter_app_api = [ ... ]` assignment, inline OR multi-line.
+ * Anchored to a line start (after optional indentation) so a same-named key inside
+ * a `[[table]]` block or a comment can't be hit. `[\s\S]*?` spans newlines for the
+ * multi-line array form; non-greedy so it stops at the FIRST closing bracket.
+ */
+const INTER_APP_API_ASSIGNMENT = /^([ \t]*)inter_app_api[ \t]*=[ \t]*\[[\s\S]*?\]/m;
+
+/**
+ * Write the registry-derived `inter_app_api` path list back into an app's manifest
+ * TOML, rewriting ONLY that one field and leaving the rest of the file
+ * byte-identical — comments, key order, whitespace, and every other field
+ * untouched. This is a surgical text edit, NOT a parse-and-re-serialize (which
+ * would clobber the comments and formatting an author put there).
+ *
+ * `inter_app_api` is auto-derived (the manifest must not drift from the code), so
+ * this is the build step's mechanism for persisting the derived list. If the field
+ * is absent it is appended; if present (inline or multi-line) its value is replaced
+ * in place.
+ *
+ * Pure: text + list in, new text out. It does not read or write files; the build
+ * step owns the I/O. It does not re-validate — the writer only ever emits a valid
+ * string array, and `Manifest.parse` remains the gate everything else reads through.
+ */
+export function writeInterAppApi(manifestText: string, paths: string[]): string {
+  const rendered = `inter_app_api = ${renderStringArray(paths)}`;
+
+  if (INTER_APP_API_ASSIGNMENT.test(manifestText)) {
+    // Replace the existing assignment, preserving its original indentation.
+    return manifestText.replace(
+      INTER_APP_API_ASSIGNMENT,
+      (_match, indent: string) => `${indent}${rendered}`,
+    );
+  }
+
+  // Absent: append it before the first `[[table]]`/`[table]` section (top-level
+  // keys must precede tables in TOML), or at the end if there are none.
+  const tableHeader = /^[ \t]*\[/m;
+  const match = tableHeader.exec(manifestText);
+  if (match) {
+    const at = match.index;
+    const before = manifestText.slice(0, at).replace(/\n*$/, "");
+    const after = manifestText.slice(at);
+    return `${before}\n${rendered}\n\n${after}`;
+  }
+
+  const trimmed = manifestText.replace(/\n*$/, "");
+  return `${trimmed}\n${rendered}\n`;
+}
+
+export const Manifest = {
+  /**
+   * Parse manifest text. Returns `{ ok: true, manifest }` on success or
+   * `{ ok: false, error }` describing either a TOML syntax failure or a list of
+   * schema violations. Never throws.
+   */
+  parse(text: string): ParseResult {
+    let raw: unknown;
+    try {
+      raw = parseToml(text);
+    } catch (err) {
+      const message = err instanceof TomlError ? err.message : String(err);
+      return { ok: false, error: { kind: "toml", message } };
+    }
+
+    const result = manifestSchema.safeParse(raw);
+    if (!result.success) {
+      return {
+        ok: false,
+        error: {
+          kind: "schema",
+          message: "manifest failed validation",
+          issues: toIssues(result.error),
+        },
+      };
+    }
+
+    return { ok: true, manifest: result.data };
+  },
+};