spec-layer 0.2.0 → 0.3.0

package/README.md

@@ -11,19 +11,48 @@ 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:
+command. Run it once in your repository:
 
 ```bash
-SPEC_LAYER_KEY=sl_... npx spec-layer pull --id lib_...
+npx spec-layer setup --id lib_... --key sl_...
 ```
 
-That writes `.speclayer/` and is enough on its own. To avoid repeating the
-library id, record it once:
+That records the library id, stores the key in a gitignored
+`speclayer.local.json`, and writes `.speclayer/`. Every later command needs no
+flags at all:
 
 ```bash
-npx spec-layer init --id lib_...
+npx spec-layer pull
 ```
 
+`init` still writes the config without a key or a network call, for a repo
+that supplies the key from the environment instead.
+
+## Installing, or not
+
+`npx` needs no install step: it fetches the package and runs it. That is the
+right choice for trying this once, and for a repo that pulls by hand.
+
+Two cases want a real install instead. On a cold cache `npx` has to fetch the
+package first, and confirming that is a prompt you do not want in an
+unattended run. `--yes` answers it up front:
+
+```bash
+npx --yes spec-layer status
+```
+
+And a repo that pulls on a schedule should pin the version rather than
+resolving the latest release on every run, so a CLI update never changes a
+build you did not touch:
+
+```bash
+npm install --save-dev spec-layer
+```
+
+`npx spec-layer` then runs the pinned local copy, no `--yes` needed. Pinning
+also keeps `.speclayer/manifest.json` on one format: 0.1.0 wrote no
+`selection` field, and 0.2.0 does.
+
 ## Commands
 
 | Command | What it does |
@@ -89,11 +118,49 @@ name, `show` refuses to guess and points you at `list`.
 
 ## The pull key
 
-Every command that talks to the server 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. The old key stops working
-once the change propagates, which can take up to about a minute.
+`spec-layer setup` stores the key in `speclayer.local.json` next to
+`speclayer.json` and makes sure git ignores it before writing it. Every later
+command in that directory needs no key. On POSIX systems the file is written
+at mode `0600`; on Windows there is no equivalent permission bit, so it
+inherits whatever the directory allows.
+
+Commands that talk to the server resolve the key in this order:
+
+1. `--key sl_...`
+2. `SPEC_LAYER_KEY` in the environment
+3. `speclayer.local.json`, when it was issued for the same library
+
+Environment sits above the file so CI can supply a key without touching the
+working tree. A stored key issued for a different library is ignored, and the
+CLI says which library it belongs to rather than letting the server answer 401.
+
+Treat the key as a secret: it grants read access to the published bundle.
+`speclayer.local.json` is gitignored, never printed by any command, and never
+copied into `speclayer.json`, `bundle.json`, `manifest.json`, or anything under
+the output directory. If it leaks, rotate it from the plugin's Library screen,
+then run the new setup command. The old key stops working once the change
+propagates, which can take up to about a minute.
+
+Re-running `setup` replaces the stored key and keeps the rest of your setup:
+with no `--out` and no selection flag it preserves the output directory and the
+`include` block already in `speclayer.json` rather than resetting them to the
+defaults. Pass `--out` or a selection flag to change them. (`init` still
+overwrites `speclayer.json` outright, which is what a first run is for.)
+
+Outside a git working tree, the key is still stored and the CLI says it left
+`.gitignore` alone. Inside one, `setup` refuses to write the key whenever it
+cannot confirm the file will be ignored, and says what to do instead. Three
+cases refuse:
+
+- `.gitignore` cannot be written.
+- git itself could not be run, anywhere inside a working tree.
+- the entry is in `.gitignore`, but git still does not ignore the file. That
+  almost always means `speclayer.local.json` is already tracked, and the CLI
+  names `git rm --cached speclayer.local.json` as the way out.
+
+git decides in every case. The entry sitting in `.gitignore` is not taken as
+proof, because `git check-ignore` does not report a tracked file as ignored no
+matter what the ignore rules say.
 
 ## What `pull` writes
 

package/dist/cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -557,7 +559,7 @@ var require_sha256 = __commonJS({
 import { parseArgs } from "node:util";
 
 // src/commands.ts
-import { join as join3 } from "node:path";
+import { join as join5 } from "node:path";
 
 // ../extractor/src/statesMatrix.ts
 var STATE_ORDER = [
@@ -822,8 +824,41 @@ function parseBundle(raw) {
 }
 
 // src/config.ts
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/credentials.ts
+import { readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
 import { join } from "node:path";
+var CREDENTIALS_NAME = "speclayer.local.json";
+var unreadable = () => new Error(
+  `${CREDENTIALS_NAME} cannot be read. Delete it, then run the setup command from the plugin's Library screen.`
+);
+function readCredentials(cwd) {
+  const path = join(cwd, CREDENTIALS_NAME);
+  if (!existsSync(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw unreadable();
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw unreadable();
+  const record = parsed;
+  if (typeof record.libraryId !== "string" || typeof record.key !== "string") throw unreadable();
+  return { libraryId: record.libraryId, key: record.key };
+}
+function writeCredentials(cwd, stored) {
+  const path = join(cwd, CREDENTIALS_NAME);
+  const replaced = existsSync(path);
+  const body = { libraryId: stored.libraryId, key: stored.key };
+  writeFileSync(path, `${JSON.stringify(body, null, 2)}
+`, { mode: 384 });
+  chmodSync(path, 384);
+  return { replaced };
+}
+
+// src/config.ts
 var DEFAULT_API = "https://api.spec-layer.com";
 var DEFAULT_OUT_DIR = ".speclayer";
 var CONFIG_NAME = "speclayer.json";
@@ -841,11 +876,11 @@ function parseInclude(value) {
   };
 }
 function readConfig(cwd) {
-  const path = join(cwd, CONFIG_NAME);
-  if (!existsSync(path)) return null;
+  const path = join2(cwd, CONFIG_NAME);
+  if (!existsSync2(path)) return null;
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync(path, "utf8"));
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
   } catch {
     throw invalidConfig();
   }
@@ -863,20 +898,31 @@ function writeConfig(cwd, config) {
     outDir: config.outDir,
     ...config.include ? { include: config.include } : {}
   };
-  writeFileSync(join(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
+  writeFileSync2(join2(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
 `);
 }
 function resolveOptions(cwd, flags, env, manifestLibraryId) {
   const config = readConfig(cwd);
   const outDir = flags.out ?? config?.outDir ?? DEFAULT_OUT_DIR;
-  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId(join(cwd, outDir));
+  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId(join2(cwd, outDir));
+  const supplied = flags.key || env.SPEC_LAYER_KEY || null;
+  let storedKey = null;
+  let storedKeyFor;
+  if (!supplied) {
+    const stored = readCredentials(cwd);
+    if (stored) {
+      if (libraryId && stored.libraryId === libraryId) storedKey = stored.key || null;
+      else storedKeyFor = stored.libraryId;
+    }
+  }
   return {
     libraryId,
     outDir,
     // A trailing slash would build "//v1/..." paths the proxy router 404s on.
     api: (flags.api ?? env.SPEC_LAYER_API ?? DEFAULT_API).replace(/\/+$/, ""),
-    key: flags.key ?? env.SPEC_LAYER_KEY ?? null,
-    ...config?.include ? { include: config.include } : {}
+    key: supplied ?? storedKey,
+    ...config?.include ? { include: config.include } : {},
+    ...storedKeyFor ? { storedKeyFor } : {}
   };
 }
 
@@ -897,7 +943,10 @@ async function fetchBundle(opts) {
   }
   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." };
+    return {
+      kind: "error",
+      message: "Key was rotated or revoked. Run the setup command from the plugin's Library screen to store 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}.` };
@@ -911,8 +960,8 @@ async function fetchBundle(opts) {
 }
 
 // src/files.ts
-import { mkdirSync, writeFileSync as writeFileSync2, readFileSync as readFileSync2, readdirSync, rmSync, renameSync, existsSync as existsSync2 } from "node:fs";
-import { join as join2, dirname, relative, resolve, isAbsolute } from "node:path";
+import { mkdirSync, writeFileSync as writeFileSync3, readFileSync as readFileSync3, readdirSync, rmSync, renameSync, existsSync as existsSync3 } from "node:fs";
+import { join as join3, dirname, relative, resolve, isAbsolute } from "node:path";
 
 // src/selection.ts
 var DEFAULT_SELECTION = { foundation: true, components: null };
@@ -951,19 +1000,19 @@ function slugify(name) {
   return slug || "component";
 }
 function readManifest(outDir) {
-  const path = join2(outDir, "manifest.json");
-  if (!existsSync2(path)) return null;
+  const path = join3(outDir, "manifest.json");
+  if (!existsSync3(path)) return null;
   try {
-    return JSON.parse(readFileSync2(path, "utf8"));
+    return JSON.parse(readFileSync3(path, "utf8"));
   } catch {
     return null;
   }
 }
 function readLocalBundle(outDir) {
-  const path = join2(outDir, "bundle.json");
-  if (!existsSync2(path)) return null;
+  const path = join3(outDir, "bundle.json");
+  if (!existsSync3(path)) return null;
   try {
-    return parseBundle(readFileSync2(path, "utf8"));
+    return parseBundle(readFileSync3(path, "utf8"));
   } catch {
     throw new Error(`${path} could not be read as a library bundle. Run spec-layer pull again.`);
   }
@@ -994,7 +1043,7 @@ function assertReplaceable(outDir, cwd) {
   if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
     throw new Error('The output directory must sit inside the current directory, not be "." or a parent of it.');
   }
-  if (existsSync2(outDir) && !existsSync2(join2(outDir, "manifest.json")) && readdirSync(outDir).length > 0) {
+  if (existsSync3(outDir) && !existsSync3(join3(outDir, "manifest.json")) && readdirSync(outDir).length > 0) {
     throw new Error(`${outDir} exists and was not written by spec-layer pull. Choose an empty or new directory.`);
   }
 }
@@ -1007,9 +1056,9 @@ function writeBundleFiles(opts) {
   rmSync(staging, { recursive: true, force: true });
   const written = [];
   const put = (rel, content) => {
-    const path = join2(staging, rel);
+    const path = join3(staging, rel);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync2(path, content);
+    writeFileSync3(path, content);
     written.push(rel);
   };
   try {
@@ -1055,6 +1104,60 @@ function writeBundleFiles(opts) {
   return written;
 }
 
+// src/gitignore.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync4 } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join as join4, dirname as dirname2, resolve as resolve2 } from "node:path";
+var COMMENT = "# Spec Layer pull key, not for committing";
+function git(cwd, args) {
+  const res = spawnSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" });
+  if (res.error || res.status === null) return { ranGit: false };
+  return { ranGit: true, status: res.status, stdout: res.stdout ?? "" };
+}
+function insideWorkTreeWithoutGit(cwd) {
+  let dir = resolve2(cwd);
+  for (; ; ) {
+    if (existsSync4(join4(dir, ".git"))) return true;
+    const parent = dirname2(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+function hasEntryLine(body, fileName) {
+  return body.split("\n").some((line) => line.trim() === fileName);
+}
+function ensureIgnored(cwd, fileName) {
+  const inWorkTree = git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (!inWorkTree.ranGit) {
+    return insideWorkTreeWithoutGit(cwd) ? { kind: "no-git", line: fileName } : { kind: "not-a-repo" };
+  }
+  if (inWorkTree.status !== 0 || inWorkTree.stdout.trim() !== "true") return { kind: "not-a-repo" };
+  const checkIgnore = git(cwd, ["check-ignore", "-q", fileName]);
+  if (checkIgnore.ranGit && checkIgnore.status === 0) return { kind: "already" };
+  const path = join4(cwd, ".gitignore");
+  const existed = existsSync4(path);
+  try {
+    if (!existed) {
+      writeFileSync4(path, `${COMMENT}
+${fileName}
+`);
+    } else {
+      const body = readFileSync4(path, "utf8");
+      if (!hasEntryLine(body, fileName)) {
+        const lead = body.length === 0 || body.endsWith("\n") ? "" : "\n";
+        writeFileSync4(path, `${body}${lead}${COMMENT}
+${fileName}
+`);
+      }
+    }
+  } catch {
+    return { kind: "refused", line: fileName };
+  }
+  const recheck = git(cwd, ["check-ignore", "-q", fileName]);
+  if (!recheck.ranGit || recheck.status !== 0) return { kind: "still-not-ignored", line: fileName };
+  return existed ? { kind: "added" } : { kind: "created" };
+}
+
 // src/commands.ts
 var NO_LOCAL_PULL = "No local pull found. Run spec-layer pull.";
 function manifestReader() {
@@ -1084,7 +1187,7 @@ function runInit(cwd, flags, io2) {
   const outDir = flags.out ?? DEFAULT_OUT_DIR;
   writeConfig(cwd, { libraryId: flags.id, outDir, ...include ? { include } : {} });
   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.");
+  io2.out(`The pull key is not stored here. Run spec-layer setup to store it in ${CREDENTIALS_NAME}, or set SPEC_LAYER_KEY.`);
   return 0;
 }
 function resolved(cwd, flags, env, io2, manifestAt) {
@@ -1096,18 +1199,18 @@ function resolved(cwd, flags, env, io2, manifestAt) {
     return null;
   }
   if (!opts.libraryId) {
-    io2.err("No library id. Pass --id lib_..., or run spec-layer init first.");
+    io2.err(opts.storedKeyFor ? `No library id. ${CREDENTIALS_NAME} holds a key for library ${opts.storedKeyFor}. Pass --id ${opts.storedKeyFor}, or run spec-layer init first.` : "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.");
+    io2.err(opts.storedKeyFor ? `The key in ${CREDENTIALS_NAME} was issued for library ${opts.storedKeyFor}, not ${opts.libraryId}. Run the setup command from the plugin's Library screen.` : "No pull key. Run the setup command from the plugin's Library screen, or set SPEC_LAYER_KEY.");
     return null;
   }
   return opts;
 }
 function resolvedOutDir(cwd, flags, io2) {
   try {
-    return join3(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
+    return join5(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
   } catch (err) {
     io2.err(errorText(err));
     return null;
@@ -1120,6 +1223,72 @@ function describePull(bundle, selection, selected) {
   if (!bundle.foundation) return components;
   return selection.foundation ? `foundation + ${components}` : `${components}, no foundation`;
 }
+async function runSetup(cwd, flags, env, io2, fetcher) {
+  if (!flags.id) {
+    io2.err("spec-layer setup needs --id lib_... (shown in the plugin after publishing).");
+    return 1;
+  }
+  const key = flags.key ?? env.SPEC_LAYER_KEY;
+  if (!key) {
+    io2.err("spec-layer setup needs --key sl_..., or SPEC_LAYER_KEY in the environment.");
+    return 1;
+  }
+  let include;
+  try {
+    include = selectionFromFlags(flags);
+  } catch (err) {
+    io2.err(errorText(err));
+    return 1;
+  }
+  let existing = null;
+  try {
+    existing = readConfig(cwd);
+  } catch {
+    existing = null;
+  }
+  const outDir = flags.out ?? existing?.outDir ?? DEFAULT_OUT_DIR;
+  const keptInclude = include ?? existing?.include ?? null;
+  writeConfig(cwd, { libraryId: flags.id, outDir, ...keptInclude ? { include: keptInclude } : {} });
+  io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}).`);
+  const ignored = ensureIgnored(cwd, CREDENTIALS_NAME);
+  switch (ignored.kind) {
+    case "refused":
+      io2.err(`Could not add ${CREDENTIALS_NAME} to .gitignore, so the key was not written.`);
+      io2.err(`Add this line to .gitignore, then run the command again:
+${ignored.line}`);
+      return 1;
+    case "no-git":
+      io2.err(`Could not run git, so it could not confirm ${CREDENTIALS_NAME} would be ignored. The key was not written.`);
+      io2.err(`Add this line to .gitignore, then run the command again:
+${ignored.line}`);
+      return 1;
+    case "still-not-ignored":
+      io2.err(`${ignored.line} is listed in .gitignore, but git still does not ignore it, so the key was not written.`);
+      io2.err(`The most likely reason is that ${ignored.line} is already tracked. Run this, then run the command again:
+git rm --cached ${ignored.line}`);
+      return 1;
+    case "created":
+      io2.out(`Created .gitignore with ${CREDENTIALS_NAME}.`);
+      break;
+    case "added":
+      io2.out(`Added ${CREDENTIALS_NAME} to .gitignore.`);
+      break;
+    case "already":
+      io2.out(`${CREDENTIALS_NAME} is already ignored by git.`);
+      break;
+    case "not-a-repo":
+      io2.out("Not a git repository, so .gitignore was left alone.");
+      break;
+    default: {
+      const exhaustive = ignored;
+      void exhaustive;
+      return 1;
+    }
+  }
+  const { replaced } = writeCredentials(cwd, { libraryId: flags.id, key });
+  io2.out(replaced ? `Replaced the stored key in ${CREDENTIALS_NAME}.` : `Stored the pull key in ${CREDENTIALS_NAME}.`);
+  return runPull(cwd, { ...flags, key }, env, io2, fetcher);
+}
 async function runPull(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
@@ -1131,7 +1300,7 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     io2.err(errorText(err));
     return 1;
   }
-  const manifest = manifestAt(join3(cwd, opts.outDir));
+  const manifest = manifestAt(join5(cwd, opts.outDir));
   const etag = manifest && sameSelection(manifest.selection ?? DEFAULT_SELECTION, selection) ? manifest.bundleHash : void 0;
   const result = await fetchBundle({
     api: opts.api,
@@ -1153,7 +1322,7 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     const bundle = parseBundle(result.raw);
     const selected = selectComponents(bundle, selection);
     written = writeBundleFiles({
-      outDir: join3(cwd, opts.outDir),
+      outDir: join5(cwd, opts.outDir),
       cwd,
       raw: result.raw,
       bundle,
@@ -1176,7 +1345,7 @@ async function runStatus(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
   if (!opts) return 1;
-  const manifest = manifestAt(join3(cwd, opts.outDir));
+  const manifest = manifestAt(join5(cwd, opts.outDir));
   if (!manifest) {
     io2.err(NO_LOCAL_PULL);
     return 2;
@@ -1267,6 +1436,8 @@ Available: ${available || "none"}.`);
 var USAGE = `spec-layer <command>
 
 Commands:
+  setup   --id lib_... --key sl_... [--out DIR] [selection]
+                                                 store the key, then pull
   init    --id lib_... [--out DIR] [selection]   write speclayer.json
   pull    [--id lib_...] [--key sl_...] [selection]
                                                  fetch the library into DIR (default .speclayer)
@@ -1275,13 +1446,13 @@ Commands:
   show    foundation | component NAME [--canonical]
                                                  print one artifact's AI YAML (or canonical JSON)
 
-Selection (pull and init; flags replace the include block in speclayer.json):
+Selection (setup, pull and init; flags replace the include block in speclayer.json):
   --only foundation | components   write just the foundation, or just components
   --component NAME                 write only this component (repeatable, matched by slug)
 
 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.`;
+The pull key comes from --key, SPEC_LAYER_KEY, or speclayer.local.json written by setup.`;
 var io = {
   out: (l) => console.log(l),
   err: (l) => console.error(l),
@@ -1312,6 +1483,7 @@ async function main() {
   const command = positionals[0];
   const cwd = process.cwd();
   try {
+    if (command === "setup") return await runSetup(cwd, values, process.env, io);
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-layer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pull design-system context published by the Spec Layer Figma plugin",
   "license": "MIT",
   "type": "module",