@terminus-ai/cli 0.0.1

package/bin/dev-contract.mjs

@@ -0,0 +1,262 @@
+/**
+ * The app-runtime wire contract as the local hosts read it: doors.json (every
+ * `/_terminus` door, and which of them `terminus dev` serves) and
+ * app-host.json (the app host's routing and header allowlists), vendored
+ * byte-for-byte from the SDK's conformance bundle under
+ * bin/vendor/app-runtime-v1/ (test/conformance.test.mjs pins the copy).
+ *
+ * The local harness routes by this table: a door the contract marks
+ * `"dev": "unsupported"` answers `501 unsupported_in_dev`, a known path with
+ * another method `405 method_not_allowed`, and anything else `404
+ * not_found` — every answer in the one error envelope, with the code and
+ * status the catalogue gives it.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { CliError } from "./client.mjs";
+
+function vendored(name) {
+  return JSON.parse(readFileSync(new URL(`./vendor/app-runtime-v1/${name}`, import.meta.url), "utf8"));
+}
+
+export const DOORS = vendored("doors.json");
+export const APP_HOST = vendored("app-host.json");
+export const LIMITS = DOORS.limits;
+
+const STATUS_BY_CODE = new Map(DOORS.errors.map((entry) => [entry.code, entry.status]));
+/** The code a refusal that names only its status answers with: the
+ * catalogue's general code for that status (403 is forbidden, never
+ * grant_required; 503 is service_unavailable, never server_disabled). */
+const CODE_BY_STATUS = new Map([
+  [400, "bad_request"],
+  [401, "unauthorized"],
+  [402, "quota_exceeded"],
+  [403, "forbidden"],
+  [404, "not_found"],
+  [405, "method_not_allowed"],
+  [409, "conflict"],
+  [413, "payload_too_large"],
+  [422, "unprocessable"],
+  [429, "rate_limited"],
+  [500, "internal_error"],
+  [501, "not_implemented"],
+  [502, "upstream_failed"],
+  [503, "service_unavailable"],
+  [504, "deadline_exceeded"],
+]);
+for (const [status, code] of CODE_BY_STATUS) {
+  if (STATUS_BY_CODE.get(code) !== status) throw new Error(`the contract has no ${status} ${code}`);
+}
+
+/** A refusal with a catalogue code; its status is the catalogue's. */
+export function runtimeError(code, message, details = undefined) {
+  const status = STATUS_BY_CODE.get(code);
+  if (!status) throw new Error(`no error code '${code}' in the contract`);
+  return Object.assign(new CliError(message), {
+    status,
+    apiCode: code,
+    ...(details === undefined ? {} : { details }),
+  });
+}
+
+/** The envelope an error answers with. A CliError without a status is a
+ * refused request (400 bad_request); anything that is not a CliError is the
+ * host's own failure (500 internal_error), as the platform answers one. */
+export function errorEnvelope(error) {
+  let status = Number(error?.status) || 0;
+  if (!status) status = error instanceof CliError ? 400 : 500;
+  const code = typeof error?.apiCode === "string" && STATUS_BY_CODE.has(error.apiCode)
+    ? error.apiCode
+    : CODE_BY_STATUS.get(status) ?? (status >= 500 ? "internal_error" : "bad_request");
+  const message = status === 500 && !(error instanceof CliError)
+    ? `internal error: ${String(error?.message ?? error)}`
+    : String(error?.message ?? error);
+  return {
+    status: STATUS_BY_CODE.get(code) ?? status,
+    body: {
+      error: {
+        code,
+        message,
+        ...(error?.details === undefined ? {} : { details: error.details }),
+      },
+    },
+  };
+}
+
+/** Answer `error` in the envelope. */
+export function sendRuntimeError(response, error) {
+  const { status, body } = errorEnvelope(error);
+  response.writeHead(status, { "content-type": "application/json" });
+  response.end(JSON.stringify(body));
+}
+
+/* ── door routing ──────────────────────────────────────────────────────── */
+
+function compileTemplate(template) {
+  const segments = template.split("/").filter(Boolean).map((segment) => {
+    const wildcard = /^\{\*([a-z_]+)\}$/u.exec(segment);
+    if (wildcard) return { wildcard: wildcard[1] };
+    const param = /^\{([a-z_]+)\}$/u.exec(segment);
+    return param ? { param: param[1] } : { literal: segment };
+  });
+  return { template, segments };
+}
+
+function matchTemplate(compiled, parts) {
+  const params = {};
+  let literals = 0;
+  for (const [index, segment] of compiled.segments.entries()) {
+    if (segment.wildcard) {
+      if (index >= parts.length) return null;
+      params[segment.wildcard] = parts.slice(index).join("/");
+      return { params, literals, wildcard: true };
+    }
+    const part = parts[index];
+    if (part === undefined) return null;
+    if (segment.literal !== undefined) {
+      if (segment.literal !== part) return null;
+      literals += 1;
+    } else {
+      params[segment.param] = part;
+    }
+  }
+  if (compiled.segments.length !== parts.length) return null;
+  return { params, literals, wildcard: false };
+}
+
+/** Every door an app can reach, by path template (a template may carry
+ * several methods). */
+const TEMPLATES = (() => {
+  const byTemplate = new Map();
+  for (const door of DOORS.doors) {
+    if (!door.path) continue;
+    if (!byTemplate.has(door.path)) byTemplate.set(door.path, { ...compileTemplate(door.path), doors: [] });
+    byTemplate.get(door.path).doors.push(door);
+  }
+  return [...byTemplate.values()];
+})();
+
+/**
+ * The door `method` `pathname` (app-relative, e.g. `/spaces/s-1/members`)
+ * names. Literal segments outrank parameters position by position, so
+ * `/collections/{collection}/changes` is never read as a record id — the way
+ * the platform's router resolves them. Answers `{ door, params }`,
+ * `{ methods }` when the path is a door's but the method is not, or null.
+ * A GET door also answers HEAD.
+ */
+export function matchDoor(method, pathname) {
+  const parts = pathname.split("/").filter(Boolean);
+  let best = null;
+  for (const template of TEMPLATES) {
+    const match = matchTemplate(template, parts);
+    if (!match) continue;
+    const rank = [match.wildcard ? 0 : 1, ...template.segments.map((segment, index) => (
+      segment.literal !== undefined && parts[index] === segment.literal ? 1 : 0
+    ))];
+    if (!best || compareRank(rank, best.rank) > 0) best = { template, match, rank };
+  }
+  if (!best) return null;
+  const verb = method === "HEAD" ? "GET" : method;
+  const door = best.template.doors.find((candidate) => candidate.method === verb);
+  if (!door) {
+    const methods = [...new Set(best.template.doors.flatMap((candidate) => (
+      candidate.method === "GET" ? ["GET", "HEAD"] : [candidate.method]
+    )))];
+    return { methods };
+  }
+  return { door, params: decodeParams(best.match.params) };
+}
+
+function compareRank(left, right) {
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference) return difference;
+  }
+  return 0;
+}
+
+function decodeParams(params) {
+  const decoded = {};
+  for (const [name, value] of Object.entries(params)) {
+    try {
+      decoded[name] = value.split("/").map((segment) => decodeURIComponent(segment)).join("/");
+    } catch {
+      throw runtimeError("bad_request", `invalid path segment for ${name}`);
+    }
+  }
+  return decoded;
+}
+
+/** The doors `terminus dev` cannot serve (the contract's `"dev":
+ * "unsupported"`). */
+export const DEV_UNSUPPORTED_DOORS = DOORS.doors.filter((door) => door.hosts.dev === "unsupported");
+
+/**
+ * Where sign-in brings a person back (`host.signin`'s `return_to`): a path on
+ * the app's own origin, and anything else is `/` — the app host's rule,
+ * written as a relative Location, which keeps the origin a request came in
+ * on (the harness's port, or the Vite dev server proxying to it).
+ *
+ * The ways a place could lead somewhere else, each answered `/`:
+ *   - nothing, or not a path at all ("https://evil.example", "evil.example");
+ *   - protocol-relative ("//evil.example"), another host on this scheme;
+ *   - a backslash anywhere ("/\evil.example"), which browsers read as "/";
+ *   - control characters: CR or LF would split the Location header, and URL
+ *     parsers drop tabs and newlines, so "/\n/evil.example" becomes
+ *     "//evil.example" after the check above had passed it;
+ *   - dot segments that collapse to protocol-relative ("/..//evil.example").
+ * And one that would fail the answer instead: a character outside Latin-1
+ * makes Node refuse the header (a 500), so the place is written the way a URL
+ * spells it — percent-encoded, query and fragment kept.
+ */
+export function returnToPath(raw) {
+  const value = typeof raw === "string" ? raw : "";
+  if (!value.startsWith("/") || value.startsWith("//") || value.includes("\\") || /\p{Cc}/u.test(value)) {
+    return "/";
+  }
+  try {
+    const url = new URL(value, "http://localhost");
+    const place = `${url.pathname}${url.search}${url.hash}`;
+    return place.startsWith("//") ? "/" : place;
+  } catch {
+    return "/";
+  }
+}
+
+/** The request fields a JSON door accepts, or null when the door takes a
+ * whole body (`$body`) or none. */
+export function requestFields(door) {
+  const fields = Object.keys(door.request ?? {});
+  if (!fields.length || fields.includes("$body")) return null;
+  return new Set(fields.map((field) => field.replace(/\?$/u, "")));
+}
+
+/** Refuse a JSON body's unknown fields, as the platform's strict grammar
+ * does ("an unknown field" is bad_request). */
+export function refuseUnknownFields(door, body) {
+  const allowed = requestFields(door);
+  if (!allowed || !body || typeof body !== "object" || Array.isArray(body)) return;
+  const unknown = Object.keys(body).find((field) => !allowed.has(field));
+  if (unknown) throw runtimeError("bad_request", `unknown field '${unknown}'`);
+}
+
+const IDEMPOTENCY_KEY = new RegExp(`^[^\\s\\p{Cc}]{1,${LIMITS.idempotency_key_chars}}$`, "u");
+
+/** The optional or required Idempotency-Key: 1-`idempotency_key_chars`
+ * visible characters. */
+export function idempotencyKey(request, { required = false, door = "this door" } = {}) {
+  const raw = request.headers["idempotency-key"];
+  if (raw === undefined || raw === "") {
+    if (required) throw runtimeError("bad_request", `${door} requires an Idempotency-Key`);
+    return null;
+  }
+  const value = Array.isArray(raw) ? raw[0] : String(raw);
+  if (!IDEMPOTENCY_KEY.test(value)) {
+    throw runtimeError(
+      "bad_request",
+      `Idempotency-Key must be 1-${LIMITS.idempotency_key_chars} visible characters`,
+    );
+  }
+  return value;
+}

package/bin/dev-data.mjs

@@ -0,0 +1,287 @@
+/**
+ * The user file plane (`/_terminus/data*`) under `terminus dev`.
+ *
+ * Zones are the platform's two: `private` (the default — the app's own area)
+ * and `output` (the person's deliverables). A `space_id` addresses the
+ * caller's own member shard in that space, private zone only; nobody reads
+ * another member's shard through this door. Bytes stay plain files under
+ * .terminus/dev/ where a developer can look at them; what a file cannot say
+ * about itself — its media type, its version, its schema — sits beside it in
+ * the system database, and every answer is the contract's FileEntry /
+ * WriteReceipt: `{path, size_bytes, sha256, media_type, version, updated_at}`.
+ */
+
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { LIMITS, runtimeError } from "./dev-contract.mjs";
+import { sha256, walkTree } from "./files.mjs";
+import { compareStrings } from "./vendor/where.mjs";
+
+const DEFAULT_MEDIA_TYPE = "application/octet-stream";
+const DEFAULT_PAGE = 100;
+
+/** A relative path with no empty, `.` or `..` segment, or null. */
+export function safeRelativePath(raw) {
+  if (typeof raw !== "string") return null;
+  const candidate = raw.replace(/^\/+/u, "");
+  if (!candidate || candidate.length > 512 || candidate.includes("\\") || candidate.includes("\0")) {
+    return null;
+  }
+  const segments = candidate.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) return null;
+  return candidate;
+}
+
+/** List prefixes may name a directory with a trailing slash ("db/notes/"). */
+export function safeListPrefix(raw) {
+  if (raw === undefined || raw === null || raw === "") return "";
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.replace(/\/+$/u, "");
+  const safe = safeRelativePath(trimmed);
+  if (safe === null) return null;
+  return raw.endsWith("/") ? `${safe}/` : safe;
+}
+
+/** `limit`: an integer, clamped to 1..page_size; `fallback` when absent. */
+export function pageLimit(raw, fallback = DEFAULT_PAGE) {
+  if (raw === null || raw === undefined || raw === "") return fallback;
+  if (!/^-?[0-9]+$/u.test(String(raw))) throw runtimeError("bad_request", "limit must be an integer");
+  return Math.max(1, Math.min(LIMITS.page_size, Number(raw)));
+}
+
+/** The media type a request says its body is, as stored. */
+export function requestMediaType(request) {
+  const raw = String(request.headers["content-type"] ?? "").trim();
+  return raw && raw.length <= 255 ? raw : DEFAULT_MEDIA_TYPE;
+}
+
+export class DevDataPlane {
+  /** `db` is the dev system database; `rootDir` the project's .terminus/dev. */
+  constructor({ rootDir, db, appId }) {
+    this.rootDir = rootDir;
+    this.db = db;
+    this.appId = appId;
+    this.locks = new Map();
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS dev_data_files (
+        app_id TEXT NOT NULL,
+        root TEXT NOT NULL,
+        path TEXT NOT NULL,
+        sha256 TEXT NOT NULL,
+        media_type TEXT NOT NULL,
+        version INTEGER NOT NULL CHECK (version > 0),
+        schema_id TEXT,
+        schema_version INTEGER,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, root, path)
+      );
+    `);
+  }
+
+  /** Where `member`'s `zone` lives, with `spaceId` naming their shard. */
+  root(member, { zone = "private", spaceId = null } = {}) {
+    if (zone !== "private" && zone !== "output") {
+      throw runtimeError("bad_request", "data zone must be private or output");
+    }
+    if (zone === "output") {
+      if (spaceId) {
+        throw runtimeError("bad_request", "a space addresses the caller's member shard, in the private zone only");
+      }
+      return { key: `output:${member}`, dir: path.join(this.rootDir, "output", member), zone };
+    }
+    if (spaceId) {
+      return {
+        key: `shard:${spaceId}:${member}`,
+        dir: path.join(this.rootDir, "spaces", spaceId, "shards", member),
+        zone,
+      };
+    }
+    return { key: `private:${member}`, dir: path.join(this.rootDir, "personal", member), zone };
+  }
+
+  /** A file path, refused when unsafe or when it is a bucket's. */
+  filePath(root, raw) {
+    const relative = safeRelativePath(raw);
+    if (!relative) throw runtimeError("bad_request", "invalid app data path");
+    if (root.zone === "private" && relative.split("/")[0] === "buckets") {
+      throw runtimeError("bad_request", "paths under buckets/ belong to storage buckets");
+    }
+    return relative;
+  }
+
+  row(root, relative) {
+    return this.db.prepare(`
+      SELECT sha256, media_type, version, schema_id, schema_version, updated_at
+      FROM dev_data_files WHERE app_id = ? AND root = ? AND path = ?
+    `).get(this.appId, root.key, relative) ?? null;
+  }
+
+  /** The FileEntry of bytes on disk: what they are, and what was said of them
+   * when they were written (a file changed behind the plane's back keeps its
+   * version and reads its own time). */
+  async entry(root, relative, bytes = null) {
+    const file = path.join(root.dir, relative);
+    const content = bytes ?? await readFile(file);
+    const digest = sha256(content);
+    const row = this.row(root, relative);
+    const current = row && String(row.sha256) === digest;
+    return {
+      path: relative,
+      size_bytes: content.length,
+      sha256: digest,
+      media_type: row ? String(row.media_type) : DEFAULT_MEDIA_TYPE,
+      version: row ? Number(row.version) : 1,
+      updated_at: current ? String(row.updated_at) : (await stat(file)).mtime.toISOString(),
+    };
+  }
+
+  /** The schema a write declared for the bytes that are there now. */
+  schema(root, relative, digest) {
+    const row = this.row(root, relative);
+    if (!row || String(row.sha256) !== digest) return { id: null, version: null };
+    return {
+      id: row.schema_id === null ? null : String(row.schema_id),
+      version: row.schema_version === null ? null : Number(row.schema_version),
+    };
+  }
+
+  /** `{files, next_cursor}`: files under `prefix` in path order, a page after
+   * `after` (the previous page's cursor). */
+  async list(root, { prefix = "", after = null, limit = DEFAULT_PAGE } = {}) {
+    const safePrefix = safeListPrefix(prefix);
+    if (safePrefix === null) throw runtimeError("bad_request", "invalid app data prefix");
+    let paths;
+    try {
+      paths = (await walkTree(root.dir)).map((file) => file.path);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      paths = [];
+    }
+    const wanted = paths
+      .filter((file) => file.startsWith(safePrefix))
+      .filter((file) => !(root.zone === "private" && file.split("/")[0] === "buckets"))
+      .sort(compareStrings)
+      .filter((file) => after === null || after === "" || compareStrings(file, after) > 0);
+    const page = wanted.slice(0, limit);
+    const files = [];
+    for (const relative of page) files.push(await this.entry(root, relative));
+    return {
+      files,
+      next_cursor: wanted.length > limit && page.length ? page.at(-1) : null,
+    };
+  }
+
+  /** One file's bytes and FileEntry; 404 when there is none. */
+  async read(root, raw) {
+    const relative = this.filePath(root, raw);
+    let bytes;
+    try {
+      bytes = await readFile(path.join(root.dir, relative));
+    } catch (error) {
+      if (error?.code === "ENOENT" || error?.code === "EISDIR") {
+        throw runtimeError("not_found", "data object not found");
+      }
+      throw error;
+    }
+    const entry = await this.entry(root, relative, bytes);
+    return { bytes, entry, schema: this.schema(root, relative, entry.sha256) };
+  }
+
+  async locked(file, task) {
+    const previous = this.locks.get(file) ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolve) => { release = resolve; });
+    this.locks.set(file, next);
+    await previous.catch(() => {});
+    try {
+      return await task();
+    } finally {
+      release();
+      if (this.locks.get(file) === next) this.locks.delete(file);
+    }
+  }
+
+  /** Compare-and-set: `missing` means the path must not exist yet. */
+  async precondition(file, expected) {
+    if (expected === null || expected === undefined) return;
+    const current = await readFile(file).catch((error) => {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    });
+    const actual = current === null ? "missing" : sha256(current);
+    if (actual !== expected) {
+      throw runtimeError(
+        "version_conflict",
+        `'${path.basename(file)}' changed: expected ${expected}, found ${actual}`,
+      );
+    }
+  }
+
+  /** Write one file → its WriteReceipt. */
+  async write(root, raw, bytes, { mediaType = DEFAULT_MEDIA_TYPE, expectedSha256 = null, schemaId = null, schemaVersion = null } = {}) {
+    const relative = this.filePath(root, raw);
+    if (bytes.length > LIMITS.data_object_bytes) {
+      throw runtimeError("payload_too_large", "a data object is at most 12 MiB");
+    }
+    const file = path.join(root.dir, relative);
+    return this.locked(file, async () => {
+      await this.precondition(file, expectedSha256);
+      await mkdir(path.dirname(file), { recursive: true });
+      await writeFile(file, bytes);
+      const prior = this.row(root, relative);
+      const updatedAt = new Date().toISOString();
+      const receipt = {
+        path: relative,
+        size_bytes: bytes.length,
+        sha256: sha256(bytes),
+        media_type: mediaType,
+        version: (prior ? Number(prior.version) : 0) + 1,
+        updated_at: updatedAt,
+      };
+      this.db.prepare(`
+        INSERT INTO dev_data_files
+          (app_id, root, path, sha256, media_type, version, schema_id, schema_version, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (app_id, root, path) DO UPDATE SET
+          sha256 = excluded.sha256,
+          media_type = excluded.media_type,
+          version = excluded.version,
+          schema_id = excluded.schema_id,
+          schema_version = excluded.schema_version,
+          updated_at = excluded.updated_at
+      `).run(
+        this.appId,
+        root.key,
+        relative,
+        receipt.sha256,
+        receipt.media_type,
+        receipt.version,
+        schemaId,
+        schemaVersion,
+        updatedAt,
+      );
+      return receipt;
+    });
+  }
+
+  /** Remove one file (a path already gone is removed all the same). */
+  async remove(root, raw, { expectedSha256 = null } = {}) {
+    const relative = this.filePath(root, raw);
+    const file = path.join(root.dir, relative);
+    return this.locked(file, async () => {
+      await this.precondition(file, expectedSha256);
+      await rm(file, { force: true });
+      this.db.prepare("DELETE FROM dev_data_files WHERE app_id = ? AND root = ? AND path = ?")
+        .run(this.appId, root.key, relative);
+      return { ok: true };
+    });
+  }
+
+  /** Every member shard of a deleted space goes with it. */
+  async removeSpace(spaceId) {
+    await rm(path.join(this.rootDir, "spaces", spaceId), { recursive: true, force: true });
+    this.db.prepare("DELETE FROM dev_data_files WHERE app_id = ? AND root LIKE ? ESCAPE '\\'")
+      .run(this.appId, `shard:${spaceId.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_")}:%`);
+  }
+}

package/bin/dev-members.mjs

@@ -0,0 +1,18 @@
+/**
+ * Who the local test members are. `--members 3` is Alan, Bob and Carol; any
+ * count from 1 through 26 draws from this one stable Alan-to-Zoe directory,
+ * and the desk's Test windows name their people from the same list, so a
+ * maker meets the same Alan and Bob whichever way they test.
+ */
+export const DEFAULT_DEV_MEMBERS = [
+  "Alan", "Bob", "Carol", "Dave", "Eve", "Frank", "Grace", "Harry", "Isabella",
+  "James", "Kate", "Lily", "Mary", "Nash", "Olivia", "Peter", "Quinn", "Rose",
+  "Sam", "Tina", "Uma", "Victor", "Wendy", "Xavier", "Yara", "Zoe",
+];
+
+/**
+ * Who plain `terminus dev` runs as: the first of them, Alan — one person
+ * testing alone is still somebody from the directory, not a member called
+ * "dev". Also the member the `data` commands read and write by default.
+ */
+export const DEFAULT_DEV_MEMBER = DEFAULT_DEV_MEMBERS[0].toLowerCase();