@sparelabs/sightline-extension-cli 0.1.0

package/dist/template.js

@@ -0,0 +1,221 @@
+// `sightline-ext init`: the files of a new extension repository. A small
+// "notes" extension: its own table, a read tool and a write tool, an audit
+// event, and an /api route, so every part of the contract is shown once.
+// The generated repository depends on the published packages only.
+import { EXT_ID_RE } from "./project.js";
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** kebab-case id → the snake_case prefix of its tool names. */
+export const toolPrefix = (id) => id.replace(/-/g, "_");
+export function templateProblems(options) {
+    const problems = [];
+    if (!EXT_ID_RE.test(options.id) || options.id.length > 40)
+        problems.push(`"${options.id}" is not an extension id: kebab-case (a-z, 0-9, -), starting with a letter, at most 40 characters`);
+    if (options.publisher !== undefined && (!EXT_ID_RE.test(options.publisher) || options.publisher.length > 40))
+        problems.push(`--publisher must be kebab-case`);
+    return problems;
+}
+export function templateFiles(options) {
+    const problems = templateProblems(options);
+    if (problems.length)
+        throw new Error(problems.join("; "));
+    const { id, packagesVersion } = options;
+    const name = options.name ?? id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+    const publisher = options.publisher ?? id;
+    const p = toolPrefix(id);
+    const range = `^${packagesVersion}`;
+    const manifest = {
+        manifestVersion: 2,
+        id,
+        name,
+        description: `${name}: notes your team keeps in Sightline.`,
+        publisher,
+        version: "0.1.0",
+        trust: "T2",
+        coreApi: "^0.1",
+        runtime: { kind: "hosted", entry: "dist/server.mjs", memoryMb: 256 },
+        permissions: [
+            { key: `${id}.read`, label: "Read notes", default: "employees" },
+            { key: `${id}.write`, label: "Write notes", default: "employees" },
+        ],
+        tools: [
+            {
+                name: `${p}_list`,
+                access: "read",
+                description: "List the most recent notes, newest first.",
+                permission: `${id}.read`,
+                surfaces: ["chat", "mcp"],
+                input: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: { limit: { type: "integer", minimum: 1, maximum: 50, description: "How many (default 10)." } },
+                },
+            },
+            {
+                name: `${p}_add`,
+                access: "write",
+                description: "Add a note.",
+                permission: `${id}.write`,
+                surfaces: ["chat", "mcp"],
+                input: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["text"],
+                    properties: { text: { type: "string", minLength: 1, maxLength: 2000, description: "The note." } },
+                },
+            },
+        ],
+        egress: { hosts: [], tenantHosts: false },
+        classification: "internal",
+    };
+    const server = `// The extension's backend. \`sightline-ext build\` bundles it into dist/server.mjs,
+// which Sightline runs in its sandbox, one instance per workspace.
+import { defineExtension, defineTool, ExtensionError, json, ok } from "@sparelabs/sightline-extension-sdk";
+import manifest from "../sightline.extension.json" with { type: "json" };
+
+// A type alias, not an interface: ctx.db rows must be indexable records.
+type Note = {
+  id: string;
+  author: string | null;
+  text: string;
+  created_at: string;
+};
+
+export default defineExtension({
+  manifest,
+  tools: {
+    ${p}_list: defineTool<{ limit?: number }>({
+      validate: ({ limit }) =>
+        limit === undefined || (typeof limit === "number" && Number.isInteger(limit) && limit >= 1 && limit <= 50) ? [] : [{ path: "limit", message: "an integer from 1 to 50" }],
+      handler: async ({ limit = 10 }, ctx) => {
+        const notes = await ctx.db<Note>\`SELECT id, author, text, created_at FROM notes ORDER BY created_at DESC LIMIT \${limit}\`;
+        return json({ notes });
+      },
+    }),
+    ${p}_add: defineTool<{ text: string }>({
+      validate: ({ text }) => (typeof text === "string" && text.trim() !== "" && text.length <= 2000 ? [] : [{ path: "text", message: "1 to 2000 characters" }]),
+      handler: async ({ text }, ctx) => {
+        if (ctx.actor.type !== "user") throw new ExtensionError("permission_denied", "notes are written by a person");
+        const [note] = await ctx.db<{ id: string }>\`INSERT INTO notes (author, text) VALUES (\${ctx.actor.userId}, \${text.trim()}) RETURNING id\`;
+        await ctx.core.audit({ action: "${id}.note_added", target: { type: "note", id: note.id } });
+        return ok("Note added.");
+      },
+    }),
+  },
+  // Your UI (if you add one) calls these through core: /functions/v1/ext-api/v1/x/${id}/api/*.
+  api: async (request, ctx) => {
+    if (request.method === "GET" && ctx.path === "/me") return Response.json(await ctx.core.me());
+    return new Response("not found", { status: 404 });
+  },
+});
+`;
+    const migration = `-- Your extension's own database, plain SQL. Add 0002_<name>.sql for the next
+-- change; never edit a migration that has been deployed (core refuses it).
+CREATE TABLE notes (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  author uuid,
+  text text NOT NULL CHECK (length(text) BETWEEN 1 AND 2000),
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX notes_created_at_idx ON notes (created_at DESC);
+`;
+    const pkg = {
+        name: id,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+            build: "sightline-ext build",
+            dev: "sightline-ext dev",
+            test: "sightline-ext test",
+            deploy: "sightline-ext deploy",
+            typecheck: "tsc -p tsconfig.json",
+        },
+        dependencies: { "@sparelabs/sightline-extension-sdk": range },
+        devDependencies: { "@sparelabs/sightline-extension-cli": range, typescript: "^5.8.3" },
+        engines: { node: ">=20.19.0" },
+    };
+    const tsconfig = {
+        compilerOptions: {
+            target: "ES2022",
+            lib: ["ES2022", "DOM"],
+            module: "ESNext",
+            moduleResolution: "bundler",
+            resolveJsonModule: true,
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+        },
+        include: ["server"],
+    };
+    const config = {
+        contract: {
+            tool: { name: `${p}_list`, input: { limit: 5 }, as: "user:alice" },
+        },
+        settings: {},
+    };
+    const ci = `name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+      - run: npm ci
+      - run: npm run typecheck
+      # Bundles, validates the manifest against the published contract, runs the
+      # extension under Sightline's runtime flags with its own Postgres (Docker),
+      # and checks it against the HTTP contract.
+      - run: npm test
+`;
+    const readme = `# ${name}
+
+A hosted [Sightline](https://www.npmjs.com/package/@sparelabs/sightline-extension-cli) extension.
+
+\`\`\`bash
+npm install
+npm run build     # bundle dist/server.mjs and validate the manifest
+npm run dev       # run it locally against an emulated Sightline (needs Deno and Docker)
+npm test          # contract tests against the emulator
+\`\`\`
+
+Deploy to a workspace with a deploy token from a workspace admin:
+
+\`\`\`bash
+SIGHTLINE_URL=https://<your workspace> SIGHTLINE_DEPLOY_TOKEN=… npx sightline-ext deploy
+\`\`\`
+
+| Path | What |
+| --- | --- |
+| \`sightline.extension.json\` | The manifest: id, version, permissions, tools |
+| \`server/main.ts\` | The backend (\`@sparelabs/sightline-extension-sdk\`) |
+| \`migrations/NNNN_<name>.sql\` | Your database, in order; only ever add files |
+| \`sightline-ext.json\` | Local only: what \`test\` calls, dev settings and secrets |
+`;
+    return {
+        "package.json": json(pkg),
+        "sightline.extension.json": json(manifest),
+        "sightline-ext.json": json(config),
+        "server/main.ts": server,
+        "migrations/0001_notes.sql": migration,
+        "tsconfig.json": json(tsconfig),
+        ".gitignore": "node_modules/\ndist/\n.sightline-devkit/\n",
+        ".github/workflows/ci.yml": ci,
+        "README.md": readme,
+    };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sparelabs/sightline-extension-cli",
+  "version": "0.1.0",
+  "description": "sightline-ext: scaffold, run, build, test and deploy a hosted Sightline extension.",
+  "license": "MIT",
+  "author": "Spare Labs Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sparelabs/sightline.git",
+    "directory": "packages/extension-cli"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "sightline-ext": "bin/sightline-ext.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@sparelabs/sightline-extension-devkit": "0.1.0",
+    "@sparelabs/sightline-extension-manifest": "0.1.0",
+    "@sparelabs/sightline-extension-testing": "0.1.0",
+    "esbuild": "^0.25.10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.16.5",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}