@sufleur/cli 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# @sufleur/cli
+
+The CLI for [**Sufleur**](https://sufleur.com) — the registry where you author, version, and publish LLM prompts. This is the consumer side: it installs prompts from your Sufleur workspace into your project the way `npm` installs packages — declared in `sufleur.yaml`, locked to `sufleur-lock.yaml`, generated into one TypeScript file with full types and runtime helpers.
+
+Create a workspace and start authoring prompts at <https://sufleur.com>.
+
+## What you call from your code
+
+```ts
+import { getPrompt } from './generated/prompts';
+
+const review = getPrompt('@my-workspace/code-review');
+
+const { prompt } = review.render('en', {
+  diff: '...',
+  language: 'go',
+});
+// → ready-to-send prompt string
+
+const result = review.parseOutput(llmResponseText);
+if (result.success) {
+  result.data; // typed by the prompt's output schema (Zod-validated)
+} else {
+  result.error;
+}
+```
+
+`'@my-workspace/code-review'` is checked at compile time: typos fail to type-check, the entrypoint name `'en'` is narrowed against the prompt's available entrypoints, and the input shape is the JSON Schema declared on that entrypoint. The version that resolves at codegen time is pinned in `sufleur-lock.yaml`.
+
+## Install
+
+```bash
+npm i -g @sufleur/cli
+sufleur --help
+```
+
+Or run on demand:
+
+```bash
+npx -p @sufleur/cli sufleur --help
+```
+
+The wrapper downloads the matching prebuilt binary on `npm install` and exposes it as `sufleur`. There's no JS in the hot path — the `sufleur` command is the native binary.
+
+## Quick start
+
+```bash
+mkdir my-app && cd my-app
+sufleur init                                  # creates sufleur.yaml interactively
+sufleur add @my-workspace/code-review ^1.0.0  # add + fetch + lock
+sufleur generate                              # writes ./generated/prompts.ts
+```
+
+The generated file imports two runtime peers — install them in your project:
+
+```bash
+npm i mustache
+npm i -D @types/mustache
+# only if any prompt has an output schema:
+npm i zod
+```
+
+## What `sufleur generate` emits
+
+A single `.ts` file containing every prompt inlined (no runtime fetches). The header documents what's exported; the public API is `getPrompt(name)`, which returns:
+
+- **`render(entrypoint, input)` → `{ prompt: string }`** — Mustache renders the entrypoint template against `input`. The input type is narrowed by entrypoint name; entrypoints with no input schema take no second argument.
+- **`metadata`** — `{ version, ...your custom workspace metadata, outputSchema? }`. The pinned version comes from the lockfile; the rest comes from whatever metadata your registry assigned to that prompt version.
+- **`parseOutput(raw)`** *(only present if the prompt has an output schema)* — strips ``` fences, JSON-parses, and validates with a Zod schema generated from the prompt's JSON Schema. Returns `{ success: true, data }` or `{ success: false, error }`.
+
+Plus exported types per entrypoint:
+
+```ts
+export type CodeReview_EnInput = { diff: string; language: string };
+```
+
+Prompts published with `DRAFT` status emit a runtime `console.warn` when their `getPrompt` is called.
+
+## sufleur.yaml
+
+The manifest. Looks like:
+
+```yaml
+api_keys:
+  my-workspace: ${MY_WORKSPACE_API_KEY}
+
+prompts:
+  '@my-workspace/greeting': '*'
+  '@my-workspace/code-review': '^2.0.0'
+  # alias: keep two pinned versions side-by-side under different names
+  '@my-workspace/code-review-strict': '@my-workspace/code-review@~1.4.0'
+
+output:
+  language: typescript
+  file: ./generated/prompts.ts
+```
+
+Constraints are npm-style semver ranges (`^`, `~`, `>=`, exact, `*`). The resolution is recorded in `sufleur-lock.yaml`. **Commit both files** — `sufleur.yaml` is the source of truth, `sufleur-lock.yaml` is the receipt.
+
+## CI usage
+
+```bash
+sufleur install --frozen   # fail if lockfile is stale
+sufleur generate
+```
+
+`--frozen` is the npm-`ci` equivalent: refuses to update the lockfile, hard-errors if the manifest and lockfile disagree.
+
+## Commands
+
+| Command | Description |
+| ------- | ----------- |
+| `sufleur init` | Interactive scaffolding for `sufleur.yaml`. |
+| `sufleur add @ws/name [range]` | Add a prompt, fetch it, update the lockfile. `--alias <name>` keeps multiple versions; `--force` overwrites an existing entry. |
+| `sufleur remove @ws/name` | Remove a prompt from the manifest and prune its cache (kept if another alias still resolves to the same version). |
+| `sufleur install` | Resolve the manifest, fetch what's missing, refresh the lockfile. `--frozen` for CI. |
+| `sufleur update [@ws/name]` | Re-resolve constraints — one prompt or all. |
+| `sufleur generate` | Regenerate the output file from the lockfile + cache. |
+
+`-v` / `--verbose` enables HTTP request/response logs on any command. Variables in `.env` are loaded automatically; per-workspace API keys can be referenced as `${ENV_VAR_NAME}` in `sufleur.yaml`.
+
+## Supported platforms
+
+| OS      | Architectures                  |
+| ------- | ------------------------------ |
+| macOS   | x64, arm64                     |
+| Linux   | x64, arm64                     |
+| Windows | x64, arm64 (Windows 10 1803+)  |
+
+Alpine / musl libc is currently unsupported (no musllinux binary). Override the binary download URL with `SUFLEUR_BINARY_MIRROR`. Set `SUFLEUR_SKIP_POSTINSTALL=1` to defer the download (e.g. when building an image you'll rehydrate later with `npm rebuild @sufleur/cli`).
+
+## Links
+
+- **Sufleur platform** — author and manage prompts: <https://sufleur.com>
+- **Source code, issues, release notes**: <https://github.com/sufleur/cli>
+
+## License
+
+MIT.

package/install.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+const { execFileSync, spawnSync } = require('child_process');
+
+const PKG = require('./package.json');
+const VERSION = PKG.version;
+
+const PLATFORM_MAP = { linux: 'linux', darwin: 'darwin', win32: 'windows' };
+const ARCH_MAP = { x64: 'amd64', arm64: 'arm64' };
+const SUPPORTED = 'linux/x64, linux/arm64, darwin/x64, darwin/arm64, win32/x64, win32/arm64';
+
+const DEFAULT_BASE = 'https://github.com/sufleur/cli/releases/download';
+const PREFIX = '[@sufleur/cli postinstall]';
+
+function fail(msg) {
+  console.error(`\n${PREFIX} ERROR: ${msg}\n`);
+  process.exit(1);
+}
+
+function info(msg) {
+  console.log(`${PREFIX} ${msg}`);
+}
+
+if (process.env.npm_config_offline === 'true') {
+  info('offline mode detected; skipping binary download. Run `npm rebuild @sufleur/cli` once online.');
+  process.exit(0);
+}
+if (process.env.SUFLEUR_SKIP_POSTINSTALL === '1') {
+  info('SUFLEUR_SKIP_POSTINSTALL=1; skipping binary download.');
+  process.exit(0);
+}
+
+const goos = PLATFORM_MAP[process.platform];
+const goarch = ARCH_MAP[process.arch];
+if (!goos || !goarch) {
+  fail(
+    `unsupported platform: ${process.platform}/${process.arch}.\n` +
+    `  Supported: ${SUPPORTED}.`
+  );
+}
+
+const isWindows = goos === 'windows';
+const ext = isWindows ? 'zip' : 'tar.gz';
+const archive = `sufleur_${VERSION}_${goos}_${goarch}.${ext}`;
+const binaryName = isWindows ? 'sufleur.exe' : 'sufleur';
+
+const base = (process.env.SUFLEUR_BINARY_MIRROR || DEFAULT_BASE).replace(/\/$/, '');
+const archiveUrl = `${base}/v${VERSION}/${archive}`;
+const checksumsUrl = `${base}/v${VERSION}/checksums.txt`;
+
+const binDir = path.join(__dirname, 'bin');
+const binTarget = path.join(binDir, binaryName);
+const cacheMarker = path.join(binDir, '.sufleur.sha256');
+fs.mkdirSync(binDir, { recursive: true });
+
+function getFollowingRedirects(rawUrl, depth = 0) {
+  return new Promise((resolve, reject) => {
+    if (depth > 5) return reject(new Error(`too many redirects: ${rawUrl}`));
+    const lib = rawUrl.startsWith('https:') ? https : http;
+    const req = lib.get(
+      rawUrl,
+      { headers: { 'user-agent': '@sufleur/cli installer' } },
+      (res) => {
+        const status = res.statusCode;
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume();
+          const next = new URL(res.headers.location, rawUrl).toString();
+          return resolve(getFollowingRedirects(next, depth + 1));
+        }
+        if (status !== 200) {
+          res.resume();
+          return reject(new Error(`GET ${rawUrl} -> HTTP ${status}`));
+        }
+        resolve(res);
+      }
+    );
+    req.on('error', (err) => reject(new Error(`fetch failed: ${rawUrl}: ${err.message}`)));
+  });
+}
+
+async function fetchText(url) {
+  const res = await getFollowingRedirects(url);
+  return await new Promise((resolve, reject) => {
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => { buf += chunk; });
+    res.on('end', () => resolve(buf));
+    res.on('error', reject);
+  });
+}
+
+async function downloadAndHash(url, destPath) {
+  const res = await getFollowingRedirects(url);
+  return await new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const out = fs.createWriteStream(destPath);
+    res.on('data', (chunk) => { hash.update(chunk); });
+    res.on('error', reject);
+    out.on('error', reject);
+    out.on('finish', () => resolve(hash.digest('hex')));
+    res.pipe(out);
+  });
+}
+
+function lookupChecksum(body, filename) {
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const parts = trimmed.split(/\s+/);
+    if (parts.length < 2) continue;
+    const [hash, name] = parts;
+    if (name === filename || name === `*${filename}`) return hash;
+  }
+  return null;
+}
+
+function readCachedHash() {
+  try {
+    return fs.readFileSync(cacheMarker, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function extractArchive(archivePath, destDir, member) {
+  // Try the system `tar` first. Modern macOS, Linux, and Windows 10 1803+
+  // all ship a libarchive-based tar that handles both .tar.gz and .zip.
+  try {
+    execFileSync('tar', ['-xf', archivePath, '-C', destDir, member], { stdio: 'inherit' });
+    return;
+  } catch (err) {
+    if (!isWindows) throw err;
+  }
+  // Windows fallback: PowerShell Expand-Archive (extracts the whole zip;
+  // the binary we want is the only member of interest).
+  const ps = spawnSync(
+    'powershell.exe',
+    [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      `Expand-Archive -Force -Path '${archivePath.replace(/'/g, "''")}' -DestinationPath '${destDir.replace(/'/g, "''")}'`
+    ],
+    { stdio: 'inherit' }
+  );
+  if (ps.status !== 0) {
+    throw new Error('PowerShell Expand-Archive failed');
+  }
+}
+
+(async function main() {
+  let expectedHex;
+  try {
+    info(`fetching checksums: ${checksumsUrl}`);
+    const checksumsBody = await fetchText(checksumsUrl);
+    expectedHex = lookupChecksum(checksumsBody, archive);
+    if (!expectedHex) {
+      fail(`no checksum entry for ${archive} in ${checksumsUrl}`);
+    }
+  } catch (err) {
+    fail(err.message);
+  }
+
+  if (fs.existsSync(binTarget) && readCachedHash() === expectedHex) {
+    info(`${binaryName} already installed (sha256 matches); skipping download.`);
+    return;
+  }
+
+  const tmp = path.join(binDir, `${archive}.partial`);
+  try {
+    info(`downloading: ${archiveUrl}`);
+    const actualHex = await downloadAndHash(archiveUrl, tmp);
+    if (actualHex !== expectedHex) {
+      try { fs.unlinkSync(tmp); } catch {}
+      fail(
+        `SHA256 mismatch for ${archive}\n` +
+        `  expected: ${expectedHex}\n` +
+        `  actual:   ${actualHex}\n` +
+        `  url:      ${archiveUrl}`
+      );
+    }
+
+    info(`extracting ${binaryName} from ${archive}`);
+    try {
+      extractArchive(tmp, binDir, binaryName);
+    } catch (err) {
+      fail(`extraction failed for ${archive}: ${err.message}`);
+    }
+
+    if (!fs.existsSync(binTarget)) {
+      fail(
+        `extraction completed but ${binTarget} is missing. ` +
+        `The archive layout may have changed (e.g. wrap_in_directory).`
+      );
+    }
+
+    if (!isWindows) {
+      fs.chmodSync(binTarget, 0o755);
+    }
+
+    fs.writeFileSync(cacheMarker, `${expectedHex}\n`);
+    info(`installed ${binaryName} at ${binTarget}`);
+  } catch (err) {
+    fail(err.message);
+  } finally {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+})();

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@sufleur/cli",
+  "version": "0.1.0",
+  "description": "CLI for sufleur — type-safe codegen for versioned LLM prompts.",
+  "keywords": [
+    "sufleur",
+    "cli",
+    "llm",
+    "prompts",
+    "codegen",
+    "typescript"
+  ],
+  "homepage": "https://github.com/sufleur/cli#readme",
+  "bugs": {
+    "url": "https://github.com/sufleur/cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sufleur/cli.git",
+    "directory": "wrappers/npm"
+  },
+  "license": "MIT",
+  "bin": {
+    "sufleur": "run.js"
+  },
+  "files": [
+    "install.js",
+    "run.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "peerDependencies": {
+    "mustache": "*",
+    "zod": "*"
+  },
+  "peerDependenciesMeta": {
+    "mustache": {
+      "optional": false
+    },
+    "zod": {
+      "optional": false
+    }
+  }
+}

package/run.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const isWindows = process.platform === 'win32';
+const binary = path.join(__dirname, 'bin', isWindows ? 'sufleur.exe' : 'sufleur');
+
+if (!fs.existsSync(binary)) {
+  console.error(
+    `\n[@sufleur/cli] Binary not found at ${binary}.\n` +
+    `Postinstall did not run, or the download failed. Try one of:\n` +
+    `  npm rebuild @sufleur/cli\n` +
+    `  node ${path.join(__dirname, 'install.js')}\n`
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+
+if (result.error) {
+  const code = result.error.code;
+  if (code === 'ENOENT') {
+    console.error(`[@sufleur/cli] could not exec ${binary}. Try: npm rebuild @sufleur/cli`);
+  } else if (code === 'EACCES') {
+    console.error(`[@sufleur/cli] permission denied executing ${binary}. Try: chmod +x ${binary}`);
+  } else {
+    console.error(`[@sufleur/cli] spawn error: ${result.error.message}`);
+  }
+  process.exit(1);
+}
+
+if (result.signal) {
+  const signo = os.constants.signals[result.signal] || 0;
+  process.exit(128 + signo);
+}
+
+process.exit(result.status === null ? 0 : result.status);