@terminus-ai/cli 0.0.1

package/bin/files.mjs

@@ -0,0 +1,169 @@
+/**
+ * Filesystem and hashing helpers shared by every command module. Like
+ * client.mjs this file knows nothing about commands or the API.
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function exists(candidate) {
+  try {
+    await stat(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** SHA-256 of `bytes`; `encoding` "buffer" returns the raw digest. */
+export function sha256(bytes, encoding = "hex") {
+  const hash = createHash("sha256").update(bytes);
+  return encoding === "buffer" ? hash.digest() : hash.digest(encoding);
+}
+
+export function pathCompare(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+/** Slash-separated path relative to `root`, the shape every package index uses. */
+export function relativePosix(root, absolute) {
+  return path.relative(root, absolute).split(path.sep).join("/");
+}
+
+/**
+ * Recursively list the regular files below `root` as `{ path, absolute, name }`
+ * sorted by relative path. `skip(relative, dirent)` prunes before descending
+ * (ignored directories are never read); `onSymlink(relative)` lets callers
+ * reject links — by default links are simply not followed.
+ */
+export async function walkTree(root, { skip = () => false, onSymlink = null } = {}) {
+  const out = [];
+  async function visit(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const absolute = path.join(dir, entry.name);
+      const relative = relativePosix(root, absolute);
+      if (skip(relative, entry)) continue;
+      if (entry.isSymbolicLink()) {
+        onSymlink?.(relative);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await visit(absolute);
+      } else if (entry.isFile()) {
+        out.push({ path: relative, absolute, name: entry.name });
+      }
+    }
+  }
+  await visit(root);
+  out.sort((left, right) => pathCompare(left.path, right.path));
+  return out;
+}
+
+/**
+ * Compile one gitignore-style pattern into a RegExp over slash paths:
+ * `**` spans directories, `*` stays inside a segment, a trailing `/` means
+ * "the directory and everything below", and a pattern without a leading `/`
+ * matches at any depth. (`path.matchesGlob` is still experimental on Node 22
+ * and prints a warning on first use, so the CLI keeps its own matcher.)
+ */
+const GLOB_CACHE = new Map();
+
+export function globToRegExp(pattern) {
+  const key = String(pattern);
+  let compiled = GLOB_CACHE.get(key);
+  if (compiled) return compiled;
+  let source = key.trim().replace(/^\/+/, "").replace(/\/+$/, "/**");
+  source = source.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  source = source.replaceAll("**", "\0").replaceAll("*", "[^/]*").replaceAll("\0", ".*");
+  compiled = new RegExp(`^(?:${source}|.*/${source})$`);
+  GLOB_CACHE.set(key, compiled);
+  return compiled;
+}
+
+/** Stream `absolute` once, producing its SHA-256, byte length, and whether
+ * it decodes as UTF-8 text (`textCandidate` gates the decode attempt). */
+export async function inspectFile(absolute, textCandidate = true) {
+  const hash = createHash("sha256");
+  let sizeBytes = 0;
+  let text = textCandidate;
+  const decoder = text ? new TextDecoder("utf-8", { fatal: true }) : null;
+  for await (const chunk of createReadStream(absolute)) {
+    hash.update(chunk);
+    sizeBytes += chunk.length;
+    if (text) {
+      if (chunk.includes(0)) {
+        text = false;
+      } else {
+        try {
+          decoder.decode(chunk, { stream: true });
+        } catch {
+          text = false;
+        }
+      }
+    }
+  }
+  if (text) {
+    try {
+      decoder.decode();
+    } catch {
+      text = false;
+    }
+  }
+  return { sha256: hash.digest("hex"), sizeBytes, text };
+}
+
+/** Run `task` over `items` with at most `concurrency` in flight; results come
+ * back in input order. */
+export async function runConcurrent(items, concurrency, task) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  const workers = Array.from(
+    { length: Math.min(concurrency, items.length) },
+    async () => {
+      while (cursor < items.length) {
+        const index = cursor;
+        cursor += 1;
+        results[index] = await task(items[index], index);
+      }
+    },
+  );
+  await Promise.all(workers);
+  return results;
+}
+
+/** Everything the CLI keeps for one project, in one folder: the working
+ *  copy's sync record beside whatever `terminus dev` made. */
+export const TERMINUS_DIRECTORY = ".terminus";
+
+/** Where `terminus dev` keeps everything it makes on this machine: the
+ *  SQLite capsules, their object storage, and an agent's workspace. It is
+ *  the disposable half — `--fresh` empties exactly this — which is why it
+ *  sits under its own name rather than beside the sync record. */
+export const DEV_DIRECTORY = path.join(TERMINUS_DIRECTORY, "dev");
+
+/**
+ * Make `<project>/.terminus/dev`, under a `.terminus/` that ignores itself,
+ * and answer with it.
+ *
+ * Git reads nested ignore files, so the databases and objects a dev run
+ * writes stay out of the developer's repository without the CLI editing the
+ * `.gitignore` they wrote. `writeSyncRecord` writes the same file; whichever
+ * runs first is enough.
+ *
+ * It takes the PROJECT directory, not the dev folder: everything it writes
+ * is then under a path it was handed. Deriving `.terminus/` by climbing out
+ * of a folder passed in is how a caller with a shallower path writes to the
+ * root of the disk.
+ */
+export async function ensureDevDirectory(projectDir) {
+  const dev = path.join(projectDir, DEV_DIRECTORY);
+  await mkdir(dev, { recursive: true });
+  // The ignore file sits at .terminus/, which covers the sync record and
+  // everything dev writes under it.
+  const ignore = path.join(projectDir, TERMINUS_DIRECTORY, ".gitignore");
+  if (!(await exists(ignore))) await writeFile(ignore, "*\n");
+  return dev;
+}

package/bin/horizontal-capabilities/v1/contract.json

@@ -0,0 +1,280 @@
+{
+  "schema_version": 1,
+  "artifact_contract": {
+    "field": "capabilities.artifacts",
+    "status": "contract_only",
+    "relationships": ["uses", "extends", "delegates", "communicates", "references"],
+    "note": "Only skill references execute today; every other edge is reserved metadata."
+  },
+  "capabilities": [
+    {
+      "id": "maps",
+      "version": "1.0.0",
+      "title": "Maps",
+      "summary": "Provider-neutral map rendering across raster (OpenStreetMap, Google, Apple) and vector (MapLibre GL over OpenFreeMap, Mapbox) lanes, with search, places, marks, 3D, directions helpers, and platform-brokered geocoding.",
+      "availability": ["app"],
+      "surfaces": {
+        "module": "assets/module.js",
+        "stylesheet": "assets/style.css",
+        "modules": {
+          "leaflet": {
+            "version": "1.9.4",
+            "asset": "assets/leaflet.js",
+            "dependencies": ["assets/leaflet.css"],
+            "license": "assets/LICENSE.leaflet.txt"
+          },
+          "maplibre": {
+            "version": "6.7.0",
+            "asset": "assets/maplibre-gl.mjs",
+            "dependencies": [
+              "assets/maplibre-gl-shared.mjs",
+              "assets/maplibre-gl-worker.mjs",
+              "assets/maplibre-gl.css"
+            ],
+            "license": "assets/LICENSE.maplibre.txt"
+          }
+        },
+        "assets": ["assets/styles.json"],
+        "operations": ["directions-url", "geocode", "provider-session"]
+      },
+      "pricing": {
+        "geocode": { "openstreetmap": "0", "mapbox": "0.002" },
+        "provider-session": { "mapbox": "0.01" }
+      },
+      "runtime_policy": {
+        "connect_src": [
+          "https://nominatim.openstreetmap.org",
+          "https://maps.googleapis.com",
+          "https://cdn.apple-mapkit.com",
+          "https://tiles.openfreemap.org",
+          "https://elevation-tiles-prod.s3.amazonaws.com",
+          "https://api.mapbox.com",
+          "https://*.tiles.mapbox.com"
+        ],
+        "img_src": [
+          "https://tile.openstreetmap.org",
+          "https://*.tile.openstreetmap.org",
+          "https://maps.googleapis.com",
+          "https://maps.gstatic.com",
+          "https://*.apple-mapkit.com",
+          "https://tiles.openfreemap.org",
+          "https://elevation-tiles-prod.s3.amazonaws.com",
+          "https://api.mapbox.com",
+          "https://*.tiles.mapbox.com"
+        ],
+        "script_src": [
+          "https://maps.googleapis.com",
+          "https://cdn.apple-mapkit.com"
+        ]
+      }
+    },
+    {
+      "id": "external-previews",
+      "version": "1.0.0",
+      "title": "External previews",
+      "summary": "Consent-scoped image previews and privacy-enhanced embedded media.",
+      "availability": ["app"],
+      "surfaces": {
+        "operations": []
+      },
+      "runtime_policy": {
+        "frame_src": [
+          "https://www.youtube-nocookie.com"
+        ],
+        "img_src": [
+          "https://i.ytimg.com"
+        ]
+      }
+    },
+    {
+      "id": "calendar",
+      "version": "1.0.0",
+      "title": "Calendar and time",
+      "summary": "Calendar interchange and timezone-safe date helpers.",
+      "availability": ["app"],
+      "surfaces": {
+        "module": "assets/module.js",
+        "operations": ["parse-ics"]
+      }
+    },
+    {
+      "id": "rendering",
+      "version": "1.0.0",
+      "title": "Rendering",
+      "summary": "A browser rendering substrate with Canvas, WebGL2, WebGPU feature negotiation, and platform-served Three.js.",
+      "availability": ["app"],
+      "surfaces": {
+        "module": "assets/module.js",
+        "modules": {
+          "three": {
+            "version": "0.185.1",
+            "asset": "assets/three.module.min.js",
+            "dependencies": ["assets/three.core.min.js"],
+            "license": "assets/LICENSE.three.txt"
+          },
+          "gltf": {
+            "version": "0.185.1",
+            "asset": "assets/gltf.module.min.js",
+            "dependencies": ["assets/three.module.min.js", "assets/three.core.min.js"],
+            "license": "assets/LICENSE.three.txt"
+          }
+        }
+      }
+    },
+    {
+      "id": "fonts",
+      "version": "1.0.0",
+      "title": "Fonts",
+      "summary": "Platform-served font faces and stable CSS variables for artifact interfaces.",
+      "availability": ["app"],
+      "surfaces": {
+        "stylesheet": "assets/fonts.css"
+      }
+    },
+    {
+      "id": "web-search",
+      "version": "1.0.0",
+      "title": "Web search",
+      "summary": "Public web search, brokered server-side through the web_search system tool's routed provider service (for example @terminus/brave-search): the platform holds the provider credential and spends the caller's shared per-user daily web budget, so no search origin reaches the page and no runtime policy is contributed. On the agent plane this same capability is the web_search tool; both planes call one broker.",
+      "availability": ["app", "agent"],
+      "agent_tool": "web_search",
+      "surfaces": {
+        "operations": ["search"]
+      }
+    },
+    {
+      "id": "web-fetch",
+      "version": "1.0.0",
+      "title": "Web fetch",
+      "summary": "SSRF-guarded public text fetch through the platform gateway, spending the caller's shared per-user daily web budget. Agent-plane only: on the agent plane this capability is the web_fetch tool; browser apps fetch public text through network_proxy (net.fetch) instead, so no app operation exists.",
+      "availability": ["agent"],
+      "agent_tool": "web_fetch",
+      "surfaces": {
+        "operations": ["fetch"]
+      }
+    },
+    {
+      "id": "bash",
+      "version": "1.0.0",
+      "title": "Shell execution",
+      "summary": "Bounded shell programs in the platform's VM-free isolate (just-bash in bashd): ~80 text-processing coreutils over the agent's own workspace (writable root and output/; package files ship read-only in place). No network, package managers, or native binaries; every run is receipted and budgeted per turn. Agent plane only: on the agent plane this capability is the bash tool.",
+      "availability": ["agent"],
+      "agent_tool": "bash",
+      "surfaces": {
+        "operations": ["exec"]
+      }
+    },
+    {
+      "id": "python",
+      "version": "1.0.0",
+      "title": "Python execution",
+      "summary": "Short standard-library-only CPython 3.13 programs in the platform's WebAssembly isolate, over the agent's lane workspace. No pip, subprocess, network, or native extensions; every run is receipted and budgeted per turn. Agent plane only: on the agent plane this capability is the python tool.",
+      "availability": ["agent"],
+      "agent_tool": "python",
+      "surfaces": {
+        "operations": ["exec"]
+      }
+    },
+    {
+      "id": "node",
+      "version": "1.0.0",
+      "title": "JavaScript execution",
+      "summary": "Short JavaScript modules on the platform's agentOS V8/WASM isolate, over the agent's lane workspace. No network, npm install, host environment, or native binaries; every run is receipted and budgeted per turn. Agent plane only: on the agent plane this capability is the node tool.",
+      "availability": ["agent"],
+      "agent_tool": "node",
+      "surfaces": {
+        "operations": ["exec"]
+      }
+    },
+    {
+      "id": "watches",
+      "version": "1.0.0",
+      "title": "Watches",
+      "summary": "Self-managed source tracking: the agent may list, create, adjust, and remove its own page watches for the installation it is talking in — the URL, extraction pattern, poll interval, wake prompt, and an optional numeric condition (percent move, or crossing below/above a level) the platform evaluates with no model spend, waking the agent only when the condition trips. Watches poll public https sources on a 15-minute floor, a repeatedly failing watch pauses itself, and the installer can disable any watch. Agent plane only: on the agent plane this capability is the manage_watches tool.",
+      "availability": ["agent"],
+      "agent_tool": "manage_watches",
+      "surfaces": {
+        "operations": ["manage"]
+      }
+    },
+    {
+      "id": "schedules",
+      "version": "1.0.0",
+      "title": "Schedules",
+      "summary": "Self-managed standing schedules: the agent may list, create, adjust, and remove its own scheduled runs for the installation it is talking in — cadence and wake prompt; every run delivers one compact notification. Schedules stay inside the per-installation schedule cap, a repeatedly failing trigger pauses itself, and the installer can disable any schedule. Agent plane only: on the agent plane this capability is the manage_schedules tool.",
+      "availability": ["agent"],
+      "agent_tool": "manage_schedules",
+      "surfaces": {
+        "operations": ["manage"]
+      }
+    },
+    {
+      "id": "image-generation",
+      "version": "1.0.0",
+      "title": "Image generation",
+      "summary": "Platform-routed image generation and editing through the image_generation system tool's provider service. Platform surfaces only today: no app or agent declares this entry directly.",
+      "availability": ["platform"],
+      "surfaces": {
+        "operations": ["generate", "edit"]
+      }
+    },
+    {
+      "id": "document-conversion",
+      "version": "1.0.0",
+      "title": "Document conversion",
+      "summary": "Platform-routed document conversion through the document_conversion system tool's provider service (for example anydoc). Platform surfaces only today: no app or agent declares this entry directly.",
+      "availability": ["platform"],
+      "surfaces": {
+        "operations": ["convert"]
+      }
+    },
+    {
+      "id": "email-delivery",
+      "version": "1.0.0",
+      "title": "Email delivery",
+      "summary": "Platform-routed email delivery through the email_delivery system tool's provider service, bounded by the provider's recipient allowlist. Platform surfaces only today: no app or agent declares this entry directly.",
+      "availability": ["platform"],
+      "surfaces": {
+        "operations": ["send"]
+      }
+    }
+  ],
+  "bundles": [
+    {
+      "id": "internet",
+      "version": "1.0.0",
+      "title": "Internet",
+      "members": ["web-search", "web-fetch"]
+    },
+    {
+      "id": "compute",
+      "version": "1.0.0",
+      "title": "Compute",
+      "members": ["bash", "python", "node"]
+    },
+    {
+      "id": "automation",
+      "version": "1.0.0",
+      "title": "Automation",
+      "members": ["schedules", "watches"]
+    },
+    {
+      "id": "media",
+      "version": "1.0.0",
+      "title": "Media",
+      "members": ["image-generation"]
+    },
+    {
+      "id": "documents",
+      "version": "1.0.0",
+      "title": "Documents",
+      "members": ["document-conversion"]
+    },
+    {
+      "id": "communication",
+      "version": "1.0.0",
+      "title": "Communication",
+      "members": ["email-delivery"]
+    }
+  ]
+}