spec-layer 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# spec-layer
+
+Pull design-system context published by the [Spec Layer](https://spec-layer.com)
+Figma plugin into your repository, so a coding agent reads the same component
+and token facts your designers see in Figma.
+
+This CLI is delivery only. It never talks to Figma, never re-derives anything,
+and has zero runtime dependencies: it fetches the bundle the plugin published
+and writes it to disk.
+
+## Quick start
+
+After publishing a library from the plugin's Library screen, it shows a setup
+command. Run it in your repository:
+
+```bash
+SPEC_LAYER_KEY=sl_... npx spec-layer pull --id lib_...
+```
+
+That writes `.speclayer/` and is enough on its own. To avoid repeating the
+library id, record it once:
+
+```bash
+npx spec-layer init --id lib_...
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init --id lib_... [--out DIR]` | Writes `speclayer.json` so later commands need no flags. |
+| `pull [--id lib_...] [--key sl_...]` | Fetches the library and writes it into `DIR` (default `.speclayer`). |
+| `status [--id lib_...] [--key sl_...]` | Checks freshness without writing. Exits `2` when the local copy is behind. |
+
+`--api URL` overrides the API origin (default `https://api.spec-layer.com`).
+
+## The pull key
+
+Every command reads the pull key from `SPEC_LAYER_KEY` or `--key`. It is never
+written to disk, and `speclayer.json` never contains it. Treat it as a secret:
+it grants read access to the published bundle. If it leaks, rotate it from the
+plugin's Library screen, which invalidates the old key immediately.
+
+## What `pull` writes
+
+```text
+.speclayer/
+  bundle.json              the published bundle, verbatim
+  manifest.json            every artifact indexed by content hash and ai path
+  ai/foundation.yaml       tokens, styles, and modes (when the library has a Foundation)
+  ai/components/<name>.yaml one file per documented component
+```
+
+Point your agent at `.speclayer/ai/`. The YAML there is the same compact form
+the plugin's **Copy for AI** puts on your clipboard; `bundle.json` additionally
+holds the full canonical artifacts if you need them.
+
+Writes stage into `.speclayer.partial` and rename into place, so an
+interrupted pull never leaves a half-written directory.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success, or `status` found the local copy up to date. |
+| `1` | Usage error, bad key or id, or a network or server failure. |
+| `2` | `status` only: the local copy is behind, or no local pull exists yet. |
+
+`status` is safe in CI: it writes nothing, and exit `2` is the signal to run
+`pull`.
+
+## Requirements
+
+Node 22 or newer. Publishing requires a Spec Layer Pro license; pulling does
+not.

package/dist/cli.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+
+// src/commands.ts
+import { join as join3 } from "node:path";
+
+// src/bundle.ts
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function contentHash(artifact) {
+  if (!isRecord(artifact) || !isRecord(artifact.spec_layer)) return null;
+  const exp = artifact.spec_layer.export;
+  if (!isRecord(exp) || typeof exp.content_hash !== "string") return null;
+  return exp.content_hash;
+}
+function entry(v, where) {
+  if (!isRecord(v) || typeof v.name !== "string" || typeof v.ai !== "string" || contentHash(v.artifact) === null) {
+    throw new Error(`The ${where} entry in this bundle is malformed.`);
+  }
+  return v;
+}
+function parseBundle(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("The server response is not valid JSON.");
+  }
+  if (!isRecord(parsed) || parsed.schema !== "spec-layer-library-bundle") {
+    throw new Error("The server response is not a Spec Layer library bundle.");
+  }
+  if (typeof parsed.version !== "string" || typeof parsed.extractorVersion !== "string" || !Array.isArray(parsed.components)) {
+    throw new Error("This bundle is missing required fields.");
+  }
+  const foundation = parsed.foundation ?? null;
+  if (foundation !== null) {
+    if (!isRecord(foundation) || typeof foundation.ai !== "string" || contentHash(foundation.artifact) === null) {
+      throw new Error("The foundation entry in this bundle is malformed.");
+    }
+  }
+  const components = parsed.components.map((c, i) => entry(c, `component ${i}`));
+  return {
+    schema: "spec-layer-library-bundle",
+    version: parsed.version,
+    fileName: typeof parsed.fileName === "string" ? parsed.fileName : null,
+    pluginVersion: typeof parsed.pluginVersion === "string" ? parsed.pluginVersion : null,
+    extractorVersion: parsed.extractorVersion,
+    foundation,
+    components
+  };
+}
+
+// src/config.ts
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+var DEFAULT_API = "https://api.spec-layer.com";
+var DEFAULT_OUT_DIR = ".speclayer";
+var CONFIG_NAME = "speclayer.json";
+function readConfig(cwd) {
+  const path = join(cwd, CONFIG_NAME);
+  if (!existsSync(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw new Error(`${CONFIG_NAME} is not valid JSON. Fix or delete it, then retry.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${CONFIG_NAME} is not valid JSON. Fix or delete it, then retry.`);
+  }
+  const record = parsed;
+  return {
+    ...typeof record.libraryId === "string" ? { libraryId: record.libraryId } : {},
+    ...typeof record.outDir === "string" ? { outDir: record.outDir } : {}
+  };
+}
+function writeConfig(cwd, config) {
+  writeFileSync(join(cwd, CONFIG_NAME), `${JSON.stringify(config, null, 2)}
+`);
+}
+function resolveOptions(cwd, flags, env, manifestLibraryId2) {
+  const config = readConfig(cwd);
+  const outDir = flags.out ?? config?.outDir ?? DEFAULT_OUT_DIR;
+  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId2(join(cwd, outDir));
+  return {
+    libraryId,
+    outDir,
+    api: flags.api ?? env.SPEC_LAYER_API ?? DEFAULT_API,
+    key: flags.key ?? env.SPEC_LAYER_KEY ?? null
+  };
+}
+
+// src/api.ts
+import { createHash } from "node:crypto";
+async function fetchBundle(opts) {
+  const doFetch = opts.fetcher ?? fetch;
+  let res;
+  try {
+    res = await doFetch(`${opts.api}/v1/libraries/${opts.libraryId}`, {
+      headers: {
+        Authorization: `Bearer ${opts.key}`,
+        ...opts.etag ? { "If-None-Match": `"${opts.etag}"` } : {}
+      }
+    });
+  } catch {
+    return { kind: "error", message: `Could not reach ${opts.api}.` };
+  }
+  if (res.status === 304) return { kind: "not_modified" };
+  if (res.status === 401) {
+    return { kind: "error", message: "Key was rotated or revoked. Ask the publisher for the current key." };
+  }
+  if (res.status === 404) return { kind: "error", message: "Library not found. It may have been unpublished." };
+  if (!res.ok) return { kind: "error", message: `Request failed with HTTP ${res.status}.` };
+  const raw = await res.text();
+  return {
+    kind: "ok",
+    raw,
+    publishedAt: res.headers.get("X-Published-At") ?? "unknown",
+    bundleHash: createHash("sha256").update(raw).digest("hex")
+  };
+}
+
+// src/files.ts
+import { mkdirSync, writeFileSync as writeFileSync2, readFileSync as readFileSync2, rmSync, renameSync, existsSync as existsSync2 } from "node:fs";
+import { join as join2, dirname } from "node:path";
+function slugify(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "component";
+}
+function readManifest(outDir) {
+  const path = join2(outDir, "manifest.json");
+  if (!existsSync2(path)) return null;
+  try {
+    return JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeBundleFiles(opts) {
+  const staging = `${opts.outDir}.partial`;
+  rmSync(staging, { recursive: true, force: true });
+  const written = [];
+  const put = (rel, content) => {
+    const path = join2(staging, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync2(path, content);
+    written.push(rel);
+  };
+  try {
+    put("bundle.json", opts.raw);
+    const artifacts = [];
+    if (opts.bundle.foundation) {
+      put("ai/foundation.yaml", opts.bundle.foundation.ai);
+      artifacts.push({
+        kind: "foundation",
+        name: "foundation",
+        contentHash: opts.bundle.foundation.artifact.spec_layer.export.content_hash,
+        aiPath: "ai/foundation.yaml"
+      });
+    }
+    const usedSlugs = /* @__PURE__ */ new Set();
+    const nextSuffix = /* @__PURE__ */ new Map();
+    for (const component of opts.bundle.components) {
+      const base = slugify(component.name);
+      let slug = base;
+      if (usedSlugs.has(slug)) {
+        let n = (nextSuffix.get(base) ?? 1) + 1;
+        slug = `${base}-${n}`;
+        while (usedSlugs.has(slug)) {
+          n += 1;
+          slug = `${base}-${n}`;
+        }
+        nextSuffix.set(base, n);
+      } else {
+        nextSuffix.set(base, 1);
+      }
+      usedSlugs.add(slug);
+      const aiPath = `ai/components/${slug}.yaml`;
+      put(aiPath, component.ai);
+      artifacts.push({
+        kind: "component",
+        name: component.name,
+        contentHash: component.artifact.spec_layer.export.content_hash,
+        aiPath
+      });
+    }
+    const manifest = {
+      libraryId: opts.libraryId,
+      publishedAt: opts.publishedAt,
+      bundleHash: opts.bundleHash,
+      pluginVersion: opts.bundle.pluginVersion,
+      extractorVersion: opts.bundle.extractorVersion,
+      artifacts
+    };
+    put("manifest.json", `${JSON.stringify(manifest, null, 2)}
+`);
+  } catch (err) {
+    rmSync(staging, { recursive: true, force: true });
+    throw err;
+  }
+  rmSync(opts.outDir, { recursive: true, force: true });
+  renameSync(staging, opts.outDir);
+  return written;
+}
+
+// src/commands.ts
+var manifestLibraryId = (outDir) => readManifest(outDir)?.libraryId ?? null;
+function runInit(cwd, flags, io2) {
+  if (!flags.id) {
+    io2.err("spec-layer init needs --id lib_... (shown in the plugin after publishing).");
+    return 1;
+  }
+  const outDir = flags.out ?? DEFAULT_OUT_DIR;
+  writeConfig(cwd, { libraryId: flags.id, outDir });
+  io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}).`);
+  io2.out("The pull key is never stored here. Set SPEC_LAYER_KEY in your environment or pass --key.");
+  return 0;
+}
+function resolved(cwd, flags, env, io2) {
+  let opts;
+  try {
+    opts = resolveOptions(cwd, flags, env, manifestLibraryId);
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    return null;
+  }
+  if (!opts.libraryId) {
+    io2.err("No library id. Pass --id lib_..., or run spec-layer init first.");
+    return null;
+  }
+  if (!opts.key) {
+    io2.err("No pull key. Set SPEC_LAYER_KEY or pass --key.");
+    return null;
+  }
+  return opts;
+}
+async function runPull(cwd, flags, env, io2, fetcher) {
+  const opts = resolved(cwd, flags, env, io2);
+  if (!opts) return 1;
+  const result = await fetchBundle({
+    api: opts.api,
+    libraryId: opts.libraryId,
+    key: opts.key,
+    ...fetcher ? { fetcher } : {}
+  });
+  if (result.kind === "error") {
+    io2.err(result.message);
+    return 1;
+  }
+  if (result.kind === "not_modified") {
+    io2.out("Already up to date.");
+    return 0;
+  }
+  let written;
+  try {
+    const bundle = parseBundle(result.raw);
+    written = writeBundleFiles({
+      outDir: join3(cwd, opts.outDir),
+      raw: result.raw,
+      bundle,
+      libraryId: opts.libraryId,
+      publishedAt: result.publishedAt,
+      bundleHash: result.bundleHash
+    });
+    const components = bundle.components.length;
+    io2.out(
+      `Pulled ${bundle.fileName ?? opts.libraryId}: ${bundle.foundation ? "foundation + " : ""}${components} component${components === 1 ? "" : "s"} (published ${result.publishedAt}).`
+    );
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+  io2.out(`Wrote ${written.length} files under ${opts.outDir}/.`);
+  return 0;
+}
+async function runStatus(cwd, flags, env, io2, fetcher) {
+  const opts = resolved(cwd, flags, env, io2);
+  if (!opts) return 1;
+  const manifest = readManifest(join3(cwd, opts.outDir));
+  if (!manifest) {
+    io2.err("No local pull found. Run spec-layer pull.");
+    return 2;
+  }
+  const result = await fetchBundle({
+    api: opts.api,
+    libraryId: opts.libraryId,
+    key: opts.key,
+    etag: manifest.bundleHash,
+    ...fetcher ? { fetcher } : {}
+  });
+  if (result.kind === "error") {
+    io2.err(result.message);
+    return 1;
+  }
+  if (result.kind === "not_modified") {
+    io2.out(`Up to date (published ${manifest.publishedAt}).`);
+    return 0;
+  }
+  io2.out(`Behind: remote published ${result.publishedAt}. Run spec-layer pull.`);
+  return 2;
+}
+
+// src/cli.ts
+var USAGE = `spec-layer <command>
+
+Commands:
+  init    --id lib_... [--out DIR]        write speclayer.json
+  pull    [--id lib_...] [--key sl_...]   fetch the library into DIR (default .speclayer)
+  status  [--id lib_...] [--key sl_...]   check freshness; exits 2 when behind
+
+Options:
+  --api URL   override the API origin (default https://api.spec-layer.com)
+The pull key comes from --key or the SPEC_LAYER_KEY environment variable.`;
+var io = { out: (l) => console.log(l), err: (l) => console.error(l) };
+async function main() {
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      allowPositionals: true,
+      options: {
+        id: { type: "string" },
+        out: { type: "string" },
+        key: { type: "string" },
+        api: { type: "string" }
+      }
+    }));
+  } catch {
+    io.err(USAGE);
+    return 1;
+  }
+  const command = positionals[0];
+  const cwd = process.cwd();
+  try {
+    if (command === "init") return runInit(cwd, values, io);
+    if (command === "pull") return await runPull(cwd, values, process.env, io);
+    if (command === "status") return await runStatus(cwd, values, process.env, io);
+    io.err(USAGE);
+    return 1;
+  } catch (err) {
+    io.err(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+process.exitCode = await main();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "spec-layer",
+  "version": "0.1.0",
+  "description": "Pull design-system context published by the Spec Layer Figma plugin",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "spec-layer": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "node build.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamsonHD/spec-layer.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://spec-layer.com",
+  "keywords": [
+    "figma",
+    "design-system",
+    "design-tokens",
+    "documentation",
+    "ai-context"
+  ]
+}