@datumos/datum-cli 0.0.0 → 0.589.0

package/cli/spaceManifestCommand.js

@@ -0,0 +1,495 @@
+/**
+ * `datum space-manifest pull|push|init <dir>` (#1809) — a space's
+ * configuration kept as files in a repository, without Terraform and
+ * without a state file (docs/space-admin/space-repository.md).
+ *
+ * Hand-written next to the derived `space-manifest list|set`, because each
+ * is a walk of a directory around one API call: `pull` turns
+ * GET /api/space-manifest into reviewable files, `push` assembles them back
+ * and sends PUT /api/space-manifest (a dry run plans, without it applies),
+ * `init` writes the repository around them. The layout itself is
+ * spaceManifestDir.ts; the repository template is spaceRepoTemplate.ts.
+ *
+ * The server stays the authority: it plans against the live space, checks
+ * references and refuses organisation-tier kinds. The CLI only refuses
+ * what must never be sent — secret material — and an org-tier kind early.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { apiSurface, UsageError } from "./invoke.js";
+import { SPACE_FILE, SpaceManifestLayoutError, buildManifest, checkManifest, countWrites, isLayoutPath, jsonFile, renderPlan, splitManifest, } from "./spaceManifestDir.js";
+import { SPACE_REPO_DATUM_OWNED, SPACE_REPO_KEY_SECRET, SPACE_REPO_MANAGED_BLOCK_FILES, recommendedSpaceRepoName, refreshManagedFile, spaceRepoFiles, } from "./spaceRepoTemplate.js";
+const SPACE_MANIFEST_PATH = "/api/space-manifest";
+/** The server's space-slug contract (`spaceSlugProblem`,
+ * server/src/spaces/spaces.interfaces.ts), mirrored because the CLI package
+ * cannot import the server; `spaceManifestCommand.test.ts` pins the two to
+ * the same verdicts. `init` must not write a repository for a slug no
+ * space can have. */
+const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+export const RESERVED_SPACE_SLUGS_MIRROR = ["www", "api", "auth", "status", "docs", "admin", "login", "llm", "relay", "push", "gw"];
+export function spaceSlugProblemMirror(slug) {
+    if (slug.length < 2 || slug.length > 40)
+        return "slug must be 2-40 characters";
+    if (!SLUG_RE.test(slug))
+        return "slug must be lowercase letters, digits and inner hyphens";
+    if (RESERVED_SPACE_SLUGS_MIRROR.includes(slug))
+        return `slug "${slug}" is reserved`;
+    if (slug.startsWith("xn--"))
+        return 'slug must not start with "xn--" (reserved for internationalised names)';
+    return null;
+}
+function line(stream, text) {
+    stream.write(`${text}\n`);
+}
+/** A refusal from the server, already human-readable. */
+class ManifestRefused extends Error {
+}
+/** The contract and the shape check on the space's host (#1824) — readable
+ * by any member, unlike the manifest itself. */
+const SPACE_MANIFEST_SCHEMA_PATH = `${SPACE_MANIFEST_PATH}/schema`;
+const SPACE_MANIFEST_VALIDATE_PATH = `${SPACE_MANIFEST_PATH}/validate`;
+/** One JSON call on the space-manifest surface; a non-2xx becomes a
+ * ManifestRefused with the server's issues and a hint for the admin 403. */
+async function callJson(method, apiPath, config, io, body) {
+    const surface = apiSurface(config);
+    const url = surface.url(apiPath);
+    const res = await (io.fetchImpl ?? fetch)(url, {
+        method,
+        headers: {
+            ...surface.headers,
+            accept: "application/json",
+            ...(body !== undefined ? { "content-type": "application/json" } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        redirect: "manual",
+    });
+    const text = await res.text();
+    let parsed = {};
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // not JSON — the message below carries the status and a snippet
+    }
+    if (!res.ok) {
+        const detail = typeof parsed.error === "string" ? parsed.error : text.slice(0, 200).trim();
+        const code = typeof parsed.code === "string" ? ` [${parsed.code}]` : "";
+        const issues = Array.isArray(parsed.issues)
+            ? parsed.issues.map((i) => `\n  ${i.path ?? "(document)"}: ${i.message ?? ""}`).join("")
+            : "";
+        const hint = res.status === 403 && /\b(?:admin|operator)\b/.test(detail)
+            ? "\n  Reading and planning the manifest need the operator role in the space, applying it the admin role" +
+                " (#1833): `datum whoami --space <slug>` shows yours. A space repository applies with a key bound to" +
+                ` the space with role admin (its ${SPACE_REPO_KEY_SECRET}); plan with --dry-run.`
+            : "";
+        throw new ManifestRefused(`HTTP ${res.status}${code} — ${detail || "no detail"} (${method} ${url})${issues}${hint}`);
+    }
+    return { status: res.status, parsed, text, url };
+}
+async function callManifest(method, config, io, body) {
+    const { status, parsed, text, url } = await callJson(method, SPACE_MANIFEST_PATH, config, io, body);
+    // A 2xx that is not the expected envelope (a proxy's HTML page, a body
+    // cut short) must never pass as an empty manifest: `pull` would clear
+    // the directory, `push` would report an empty plan as success.
+    const valid = method === "GET"
+        ? typeof parsed.apiVersion === "string" && typeof parsed.spaceId === "string"
+        : typeof parsed.spaceId === "string" && Array.isArray(parsed.plan) && typeof parsed.applied === "boolean";
+    if (!valid) {
+        throw new ManifestRefused(`HTTP ${status} with an unexpected answer — not a space manifest response (${method} ${url}): ${text.slice(0, 200).trim() || "(empty body)"}`);
+    }
+    return parsed;
+}
+/** `pull` records which space the directory mirrors (its id); `push`
+ * refuses to send the files to another one. A dotfile, so the layout
+ * never reads it as a kind. */
+export const SPACE_ID_MARKER = ".space-id";
+/** Every file under `dir` the layout owns (known kinds only), relative and `/`-separated. */
+function readLayout(dir, extraKinds = new Set()) {
+    const files = {};
+    for (const name of fs.readdirSync(dir)) {
+        if (name.startsWith("."))
+            continue;
+        const abs = path.join(dir, name);
+        const stat = fs.lstatSync(abs);
+        if (stat.isFile() && isLayoutPath(name, extraKinds))
+            files[name] = fs.readFileSync(abs, "utf8");
+        if (!stat.isDirectory())
+            continue;
+        for (const child of fs.readdirSync(abs)) {
+            const rel = `${name}/${child}`;
+            const childAbs = path.join(abs, child);
+            if (fs.lstatSync(childAbs).isFile() && isLayoutPath(rel, extraKinds)) {
+                files[rel] = fs.readFileSync(childAbs, "utf8");
+            }
+        }
+    }
+    return files;
+}
+/** The first symlink among <dir>, the kind folders and the files `rels`
+ * name (relative to <dir>) — null when every existing component is real. */
+function symlinkOnPath(dir, rels) {
+    const isLink = (p) => {
+        try {
+            return fs.lstatSync(p).isSymbolicLink();
+        }
+        catch {
+            return false; // absent — created as a real file or folder
+        }
+    };
+    if (isLink(dir))
+        return dir;
+    const seen = new Set();
+    for (const rel of rels) {
+        const parts = rel.split("/");
+        for (let i = 1; i <= parts.length; i += 1) {
+            const p = path.join(dir, ...parts.slice(0, i));
+            if (seen.has(p))
+                continue;
+            seen.add(p);
+            if (isLink(p))
+                return p;
+        }
+    }
+    // Kind folders the layout would read (and empty) even if the space no
+    // longer has them.
+    for (const name of fs.existsSync(dir) ? fs.readdirSync(dir) : []) {
+        const p = path.join(dir, name);
+        if (isLayoutPath(`${name}/x.json`) && isLink(p))
+            return p;
+    }
+    return null;
+}
+function readMarker(dir) {
+    try {
+        return fs.readFileSync(path.join(dir, SPACE_ID_MARKER), "utf8").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+// -------------------------------------------------------------------- pull
+export async function runSpaceManifestPull(args, config, io) {
+    const dir = path.resolve(args.dir);
+    if (fs.existsSync(dir)) {
+        if (!fs.statSync(dir).isDirectory()) {
+            line(io.err, `datum: ${args.dir} is not a directory`);
+            return 2;
+        }
+        // Never clear a directory that is not a manifest directory: `pull .` in
+        // a repository root must not touch the README, the workflows or src/.
+        const all = fs.readdirSync(dir);
+        if (all.includes(".git") || all.includes(".github")) {
+            line(io.err, `datum: ${args.dir} is a repository root — pull into a folder of it, e.g. \`datum space-manifest pull space\``);
+            return 2;
+        }
+        const entries = all.filter((n) => !n.startsWith("."));
+        if (entries.length > 0 && !entries.includes(SPACE_FILE)) {
+            line(io.err, `datum: ${args.dir} holds files but no ${SPACE_FILE} — pull writes into an empty directory or one it wrote before (e.g. \`datum space-manifest pull space\`)`);
+            return 2;
+        }
+    }
+    let live;
+    try {
+        live = await callManifest("GET", config, io);
+    }
+    catch (err) {
+        return reportFailure(err, io);
+    }
+    const { files, skipped } = splitManifest(live);
+    const spaceId = typeof live.spaceId === "string" ? live.spaceId : null;
+    const marker = fs.existsSync(dir) ? readMarker(dir) : null;
+    if (marker && spaceId && marker !== spaceId) {
+        line(io.err, `datum: ${args.dir} mirrors the space ${marker}, but this credential answers for the space ${spaceId} — ` +
+            "a key is bound to ONE space whatever --space says; use that space's key (or pull into another directory)");
+        return 1;
+    }
+    // Every write below follows the path it is given — a symlinked <dir>,
+    // kind folder or file (a checked-in `space/agents -> ../..`) would carry
+    // them outside the directory, on a self-hosted runner too. Refuse before
+    // the first deletion.
+    const symlink = symlinkOnPath(dir, [...Object.keys(files), SPACE_ID_MARKER]);
+    if (symlink) {
+        line(io.err, `datum: ${symlink} is a symbolic link — pull writes only real files and folders inside ${args.dir}`);
+        return 1;
+    }
+    // The directory mirrors the space: a layout file whose entry is gone
+    // disappears (and is named, so an uncommitted hand-written entry is not
+    // lost silently); files outside the layout are never touched.
+    const removed = [];
+    if (fs.existsSync(dir)) {
+        for (const rel of Object.keys(readLayout(dir))) {
+            if (!(rel in files))
+                removed.push(rel);
+            fs.rmSync(path.join(dir, rel));
+        }
+        for (const name of fs.readdirSync(dir)) {
+            const abs = path.join(dir, name);
+            if (isLayoutPath(`${name}/x.json`) && fs.lstatSync(abs).isDirectory() && fs.readdirSync(abs).length === 0) {
+                fs.rmdirSync(abs);
+            }
+        }
+    }
+    for (const [rel, content] of Object.entries(files)) {
+        const target = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, content);
+    }
+    if (spaceId)
+        fs.writeFileSync(path.join(dir, SPACE_ID_MARKER), `${spaceId}\n`);
+    line(io.out, `pulled ${Object.keys(files).length} files into ${args.dir}${spaceId ? ` (space ${spaceId})` : ""}`);
+    for (const rel of removed.sort())
+        line(io.out, `  removed ${rel} — not in the space`);
+    const org = skipped.filter((s) => s.reason.startsWith("organisation")).map((s) => s.kind);
+    const empty = skipped.filter((s) => s.reason.startsWith("empty")).map((s) => s.kind);
+    const unknown = skipped.filter((s) => s.reason.startsWith("unknown")).map((s) => s.kind);
+    if (org.length)
+        line(io.out, `  left out (organisation tier, the org admin's): ${org.join(", ")}`);
+    if (empty.length)
+        line(io.out, `  left out (empty in the space): ${empty.join(", ")}`);
+    if (unknown.length) {
+        line(io.err, `warning: left out kinds this CLI does not know — run \`datum update\`, then pull again: ${unknown.join(", ")}`);
+    }
+    return 0;
+}
+export async function runSpaceManifestPush(args, config, io) {
+    const dir = path.resolve(args.dir);
+    if (!fs.existsSync(path.join(dir, SPACE_FILE))) {
+        line(io.err, `datum: ${args.dir} has no ${SPACE_FILE} — run \`datum space-manifest pull ${args.dir}\` first`);
+        return 2;
+    }
+    let spec;
+    try {
+        spec = buildManifest(readLayout(dir));
+    }
+    catch (err) {
+        if (err instanceof SpaceManifestLayoutError) {
+            line(io.err, `datum: ${args.dir}/${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    const { errors, warnings } = checkManifest(spec);
+    for (const w of warnings)
+        line(io.err, `warning: ${w}`);
+    if (errors.length > 0) {
+        for (const e of errors)
+            line(io.err, `datum: ${e}`);
+        return 1;
+    }
+    // A key is bound to ONE space whatever host or --space it is sent to, so
+    // the wrong repository secret would apply this space's files to another
+    // space. The directory remembers which space `pull` read: a dry run
+    // first names the space the credential answers for, and an apply goes
+    // ahead only when that is the same one.
+    const marker = readMarker(dir);
+    if (!marker) {
+        line(io.err, `datum: ${args.dir}/${SPACE_ID_MARKER} is missing — it names the space these files belong to; ` +
+            `\`datum space-manifest pull ${args.dir}\` writes it (with the key of that space)`);
+        return 2;
+    }
+    let answer;
+    try {
+        const body = { spec, prune: args.prune };
+        answer = (await callManifest("PUT", config, io, { ...body, dryRun: true }));
+        if (answer.spaceId !== marker) {
+            line(io.err, `datum: ${args.dir} mirrors the space ${marker}, but this credential answers for the space ${answer.spaceId} — ` +
+                "nothing was written; use the key bound to the directory's space");
+            return 1;
+        }
+        if (!args.dryRun)
+            answer = (await callManifest("PUT", config, io, { ...body, dryRun: false }));
+    }
+    catch (err) {
+        return reportFailure(err, io);
+    }
+    const markdown = renderPlan(answer, args.dryRun ? "Datum space plan" : "Datum space apply");
+    if (args.markdown)
+        fs.writeFileSync(args.markdown, markdown);
+    io.out.write(args.json ? jsonFile(answer) : markdown);
+    if (args.expectEmpty && countWrites(answer) > 0) {
+        line(io.err, `datum: expected an empty plan, got ${countWrites(answer)} write(s) — the space and the files disagree ` +
+            "(a value the server normalises: write it the way the plan shows; or an edit racing this run)");
+        return 1;
+    }
+    return 0;
+}
+// ---------------------------------------------------------------- validate
+/**
+ * `validate <dir>` (#1824): assembles the files the way `push` does — the
+ * `$file` references, the local refusals of key material and org-tier
+ * kinds — and sends the document to the shape check on the space's host.
+ * Any member may run it (no admin role, no `.space-id`, nothing written):
+ * the check an agent runs before it opens a pull request. References bound
+ * to the live space (credential labels, board queries) wait for the plan.
+ */
+export async function runSpaceManifestValidate(args, config, io) {
+    const dir = path.resolve(args.dir);
+    if (!fs.existsSync(path.join(dir, SPACE_FILE))) {
+        line(io.err, `datum: ${args.dir} has no ${SPACE_FILE} — validate reads a directory \`pull\` wrote (e.g. space/)`);
+        return 2;
+    }
+    let spec;
+    try {
+        spec = buildManifest(readLayout(dir));
+    }
+    catch (err) {
+        if (err instanceof SpaceManifestLayoutError) {
+            line(io.err, `datum: ${args.dir}/${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    const { errors, warnings } = checkManifest(spec);
+    for (const w of warnings)
+        line(io.err, `warning: ${w}`);
+    if (errors.length > 0) {
+        for (const e of errors)
+            line(io.err, `datum: ${e}`);
+        return 1;
+    }
+    let checked;
+    try {
+        const { parsed, text, url } = await callJson("POST", SPACE_MANIFEST_VALIDATE_PATH, config, io, { spec });
+        if (parsed.ok !== true) {
+            throw new ManifestRefused(`unexpected answer from POST ${url}: ${text.slice(0, 200).trim() || "(empty body)"}`);
+        }
+        checked = parsed.checked;
+    }
+    catch (err) {
+        return reportFailure(err, io);
+    }
+    const kinds = Object.keys(spec).filter((k) => k !== "apiVersion");
+    const entries = kinds.reduce((n, k) => n + (Array.isArray(spec[k]) ? spec[k].length : 1), 0);
+    // Below admin the server checks the shape only (its reference checks read
+    // admin/org data) — say so, so "valid" is not read as "the plan will pass".
+    const scope = checked === "shape"
+        ? ` (shape only — run \`datum space-manifest push ${args.dir} --dry-run\` as a space admin for the full check)`
+        : checked === "full"
+            ? " (the dry run's full check, without the plan)"
+            : "";
+    line(io.out, `${args.dir}: valid${scope} — ${kinds.length} kinds, ${entries} entries. Next: \`datum space-manifest push ${args.dir} --dry-run\` (or a pull request) for the plan against the live space.`);
+    return 0;
+}
+// ------------------------------------------------------------------ schema
+/**
+ * `schema [kind]` (#1824): the manifest's JSON Schema from the space's
+ * host — whole, or the one kind an agent is about to write (its fields,
+ * their descriptions and the x-datum-* metadata). An unknown kind lists
+ * the kinds this instance offers.
+ */
+export async function runSpaceManifestSchema(args, config, io) {
+    let schema;
+    try {
+        ({ parsed: schema } = await callJson("GET", SPACE_MANIFEST_SCHEMA_PATH, config, io));
+    }
+    catch (err) {
+        return reportFailure(err, io);
+    }
+    const properties = (schema.properties ?? {});
+    if (args.kind === undefined) {
+        io.out.write(jsonFile(schema));
+        return 0;
+    }
+    if (!(args.kind in properties)) {
+        const kinds = Object.keys(properties).filter((k) => k !== "apiVersion").sort();
+        line(io.err, `datum: no manifest kind "${args.kind}" on this instance — kinds: ${kinds.join(", ")}`);
+        return 2;
+    }
+    io.out.write(jsonFile(properties[args.kind]));
+    return 0;
+}
+// -------------------------------------------------------------------- init
+export function runSpaceManifestInit(args, io) {
+    if (!args.space) {
+        line(io.err, "datum: init needs the space — pass --space <slug> (or set DATUM_SPACE)");
+        return 2;
+    }
+    const slugProblem = spaceSlugProblemMirror(args.space);
+    if (slugProblem) {
+        line(io.err, `datum: "${args.space}" is not a space slug — ${slugProblem}`);
+        return 2;
+    }
+    const dir = path.resolve(args.dir);
+    const files = spaceRepoFiles(args.space);
+    const symlink = symlinkOnPath(dir, Object.keys(files));
+    if (symlink) {
+        line(io.err, `datum: ${symlink} is a symbolic link — init writes only real files and folders inside ${args.dir}`);
+        return 1;
+    }
+    const written = [];
+    const refreshed = [];
+    const kept = [];
+    for (const [rel, content] of Object.entries(files)) {
+        const target = path.join(dir, rel);
+        if (fs.existsSync(target)) {
+            // AGENTS.md / CLAUDE.md: Datum's block is refreshed on every run
+            // (#1824) — the rules move with Datum, the team's notes stay.
+            if (SPACE_REPO_MANAGED_BLOCK_FILES.has(rel)) {
+                const next = refreshManagedFile(fs.readFileSync(target, "utf8"), content);
+                if (next === null) {
+                    kept.push(rel);
+                }
+                else {
+                    fs.writeFileSync(target, next);
+                    refreshed.push(rel);
+                }
+                continue;
+            }
+            // The workflows: Datum's whole, replaced only on --refresh.
+            if (args.refresh && SPACE_REPO_DATUM_OWNED.has(rel)) {
+                if (fs.readFileSync(target, "utf8") !== content) {
+                    fs.writeFileSync(target, content);
+                    refreshed.push(rel);
+                }
+                else {
+                    kept.push(rel);
+                }
+                continue;
+            }
+            // A repository created in Cloud Market may already carry a
+            // README or a .gitignore: never overwrite a person's file.
+            kept.push(rel);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, content);
+        written.push(rel);
+    }
+    for (const rel of written)
+        line(io.out, `wrote ${rel}`);
+    for (const rel of refreshed)
+        line(io.out, `refreshed ${rel} (Datum's part, current version)`);
+    for (const rel of kept) {
+        const hint = SPACE_REPO_DATUM_OWNED.has(rel) && !args.refresh
+            ? " — `--refresh` replaces it with the current version"
+            : SPACE_REPO_MANAGED_BLOCK_FILES.has(rel)
+                ? " — already current"
+                : " — compare it with `datum space-manifest init <empty dir>`";
+        line(io.out, `kept ${rel} (exists${hint})`);
+    }
+    if (refreshed.length > 0 && written.length === 0) {
+        line(io.out, "");
+        line(io.out, "Commit the refreshed files in a pull request.");
+        return 0;
+    }
+    line(io.out, "");
+    line(io.out, `Next, for the space "${args.space}" (recommended repository name: ${recommendedSpaceRepoName(args.space)}):`);
+    line(io.out, "  1. commit and push these files;");
+    line(io.out, "  2. repository variable DATUM_BASE_URL = the organisation host;");
+    line(io.out, `  3. a space admin mints a key bound to the space (panel: Settings → API keys, role admin) and stores it as the repository secret ${SPACE_REPO_KEY_SECRET} — never in a file or a chat;`);
+    line(io.out, '  4. Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests" (the sync opens pull requests);');
+    line(io.out, "  5. Actions → Datum space sync → Run workflow, then merge the import pull request.");
+    return 0;
+}
+function reportFailure(err, io) {
+    if (err instanceof ManifestRefused) {
+        line(io.err, `datum: ${err.message}`);
+        return 1;
+    }
+    if (err instanceof UsageError) {
+        line(io.err, `datum: ${err.message}`);
+        return 2;
+    }
+    throw err;
+}
+//# sourceMappingURL=spaceManifestCommand.js.map