@alvera-ai/platform-sdk 0.10.0-rc.2 → 0.10.0-rc.21

package/dist/bin/platform-sdk.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/llm-export.ts
+const MARKER_BEGIN = "<!-- @alvera-ai/platform-sdk:BEGIN -->";
+const MARKER_END = "<!-- @alvera-ai/platform-sdk:END -->";
+const CLAUDE_IMPORT_LINE = "@AGENTS.md";
+const SDK_PACKAGE_NAME = "@alvera-ai/platform-sdk";
+function buildManagedBlock() {
+	const corpus = `node_modules/${SDK_PACKAGE_NAME}/.agent`;
+	return [
+		MARKER_BEGIN,
+		"",
+		"<!-- Managed by `alvera llm-export` — do not edit by hand. -->",
+		"<!-- Re-running the command replaces only this block. -->",
+		"",
+		`## \`${SDK_PACKAGE_NAME}\` corpus`,
+		"",
+		"The SDK ships an agent-docs corpus next to its npm install. Read the",
+		"corpus index first (Claude Code inlines this import):",
+		"",
+		`@${corpus}/AGENTS.md`,
+		"",
+		`Cookbook recipes live under \`${corpus}/cookbook/\`.`,
+		"",
+		"### Top-3 consumer gotchas",
+		"",
+		"1. **Updates use PUT, not PATCH.** The SDK exposes no PATCH method;",
+		`   mutations replace the resource whole. See \`${corpus}/mutations.md\`.`,
+		"2. **Paginated catalogs return `{ data, meta }`.** Catalog endpoints",
+		"   (`tools.list`, `dataSources.list`, etc.) wrap rows in `data` with a",
+		"   `meta` envelope — destructure, do not iterate the response directly.",
+		"3. **Resources are datalake-slug-scoped.** Every nested URL takes both",
+		"   `tenantSlug` and `datalakeSlug` — never a single slug. The datalake",
+		"   slug comes from the server (`api.datalakes.create`'s response).",
+		"",
+		MARKER_END
+	].join("\n");
+}
+function upsertManagedBlock(target, block) {
+	const beginIdx = target.indexOf(MARKER_BEGIN);
+	const endIdx = target.indexOf(MARKER_END);
+	if (beginIdx === -1 && endIdx === -1) return target + (target.length === 0 ? "" : target.endsWith("\n\n") ? "" : target.endsWith("\n") ? "\n" : "\n\n") + block + "\n";
+	if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) throw new Error(`AGENTS.md: managed-block markers are damaged (BEGIN at ${beginIdx}, END at ${endIdx}). Fix by hand or remove both markers, then re-run llm-export.`);
+	const before = target.slice(0, beginIdx);
+	const after = target.slice(endIdx + 36);
+	return before + block + after;
+}
+function upsertClaudeImport(target) {
+	if (target.split("\n").some((line) => line.trim() === CLAUDE_IMPORT_LINE)) return {
+		next: target,
+		written: false
+	};
+	return {
+		next: target + (target.length === 0 ? "" : target.endsWith("\n\n") ? "" : target.endsWith("\n") ? "\n" : "\n\n") + CLAUDE_IMPORT_LINE + "\n",
+		written: true
+	};
+}
+function readOrEmpty(path) {
+	return existsSync(path) ? readFileSync(path, "utf8") : "";
+}
+function runLlmExport(cwd = process.cwd()) {
+	const block = buildManagedBlock();
+	const agentsMdPath = join(cwd, "AGENTS.md");
+	writeFileSync(agentsMdPath, upsertManagedBlock(readOrEmpty(agentsMdPath), block), "utf8");
+	const claudeMdPath = join(cwd, "CLAUDE.md");
+	const { next: claudeAfter, written: claudeImportWritten } = upsertClaudeImport(readOrEmpty(claudeMdPath));
+	writeFileSync(claudeMdPath, claudeAfter, "utf8");
+	return {
+		agentsMdPath,
+		claudeMdPath,
+		managedBlockBytes: block.length,
+		claudeImportWritten
+	};
+}
+
+//#endregion
+//#region src/bin/platform-sdk.ts
+function usage() {
+	process.stderr.write("Usage: npx @alvera-ai/platform-sdk <command>\n\nCommands:\n  llm-export    Write a managed AGENTS.md block pointing at the\n                SDK agent-docs corpus in node_modules; ensure\n                CLAUDE.md imports AGENTS.md. Idempotent.\n");
+}
+function main() {
+	const command = process.argv[2];
+	if (command === void 0 || command === "--help" || command === "-h") {
+		usage();
+		process.exit(command === void 0 ? 1 : 0);
+	}
+	if (command === "llm-export") try {
+		const result = runLlmExport(process.cwd());
+		process.stderr.write(`✓ ${result.agentsMdPath} (${result.managedBlockBytes} bytes in managed block)\n`);
+		process.stderr.write(`✓ ${result.claudeMdPath}${result.claudeImportWritten ? " (added @AGENTS.md import)" : " (@AGENTS.md import already present)"}\n`);
+		return;
+	} catch (err) {
+		process.stderr.write(`llm-export failed: ${err instanceof Error ? err.message : String(err)}\n`);
+		process.exit(1);
+	}
+	process.stderr.write(`unknown command "${command}".\n\n`);
+	usage();
+	process.exit(1);
+}
+main();
+
+//#endregion
+export {  };
+//# sourceMappingURL=platform-sdk.mjs.map

package/dist/bin/platform-sdk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-sdk.mjs","names":[],"sources":["../../src/llm-export.ts","../../src/bin/platform-sdk.ts"],"sourcesContent":["// Consumer-facing agent-docs injector — the SDK-bin home of\n// `llm-export`. Writes a managed block into <cwd>/AGENTS.md that POINTS\n// at this package's shipped `.agent/` corpus (predictable npm path), and\n// ensures <cwd>/CLAUDE.md imports AGENTS.md.\n//\n// This writer is DUPLICATED in the CLI (packages/cli/src/cli/llm-export.ts)\n// for the brew `alvera llm-export` path. The two copies must emit a\n// byte-identical block — `buildManagedBlock()` below is kept verbatim in\n// both, and each package snapshot-tests its own output (architecture-\n// decisions §2.10.13). They are not shared via import: the CLI's tsconfig\n// rootDir forbids importing SDK source, a public SDK export was rejected\n// to keep the surface lean (CLAUDE.md #6), and the sharing would be\n// throwaway under a future Go CLI anyway.\n//\n// Unlike the CLI copy, this one is a LIBRARY module: it throws on damaged\n// markers rather than calling process.exit — the bin entry catches and\n// exits.\nimport { existsSync, readFileSync, writeFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nconst MARKER_BEGIN = '<!-- @alvera-ai/platform-sdk:BEGIN -->'\nconst MARKER_END = '<!-- @alvera-ai/platform-sdk:END -->'\nconst CLAUDE_IMPORT_LINE = '@AGENTS.md'\nconst SDK_PACKAGE_NAME = '@alvera-ai/platform-sdk'\n\nexport interface LlmExportResult {\n  agentsMdPath: string\n  claudeMdPath: string\n  managedBlockBytes: number\n  claudeImportWritten: boolean\n}\n\n// Pure + deterministic. MUST stay byte-identical to the CLI copy's\n// buildManagedBlock (§2.10.13 drift guard).\nexport function buildManagedBlock(): string {\n  const corpus = `node_modules/${SDK_PACKAGE_NAME}/.agent`\n  const lines: string[] = [\n    MARKER_BEGIN,\n    '',\n    '<!-- Managed by `alvera llm-export` — do not edit by hand. -->',\n    '<!-- Re-running the command replaces only this block. -->',\n    '',\n    `## \\`${SDK_PACKAGE_NAME}\\` corpus`,\n    '',\n    'The SDK ships an agent-docs corpus next to its npm install. Read the',\n    'corpus index first (Claude Code inlines this import):',\n    '',\n    `@${corpus}/AGENTS.md`,\n    '',\n    `Cookbook recipes live under \\`${corpus}/cookbook/\\`.`,\n    '',\n    '### Top-3 consumer gotchas',\n    '',\n    '1. **Updates use PUT, not PATCH.** The SDK exposes no PATCH method;',\n    `   mutations replace the resource whole. See \\`${corpus}/mutations.md\\`.`,\n    '2. **Paginated catalogs return `{ data, meta }`.** Catalog endpoints',\n    '   (`tools.list`, `dataSources.list`, etc.) wrap rows in `data` with a',\n    '   `meta` envelope — destructure, do not iterate the response directly.',\n    '3. **Resources are datalake-slug-scoped.** Every nested URL takes both',\n    '   `tenantSlug` and `datalakeSlug` — never a single slug. The datalake',\n    \"   slug comes from the server (`api.datalakes.create`'s response).\",\n    '',\n    MARKER_END,\n  ]\n  return lines.join('\\n')\n}\n\nexport function upsertManagedBlock(target: string, block: string): string {\n  const beginIdx = target.indexOf(MARKER_BEGIN)\n  const endIdx = target.indexOf(MARKER_END)\n\n  if (beginIdx === -1 && endIdx === -1) {\n    const tail =\n      target.length === 0\n        ? ''\n        : target.endsWith('\\n\\n')\n          ? ''\n          : target.endsWith('\\n')\n            ? '\\n'\n            : '\\n\\n'\n    return target + tail + block + '\\n'\n  }\n\n  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {\n    throw new Error(\n      `AGENTS.md: managed-block markers are damaged ` +\n        `(BEGIN at ${beginIdx}, END at ${endIdx}). ` +\n        `Fix by hand or remove both markers, then re-run llm-export.`,\n    )\n  }\n\n  const before = target.slice(0, beginIdx)\n  const after = target.slice(endIdx + MARKER_END.length)\n  return before + block + after\n}\n\nexport function upsertClaudeImport(target: string): { next: string; written: boolean } {\n  const already = target.split('\\n').some((line) => line.trim() === CLAUDE_IMPORT_LINE)\n  if (already) return { next: target, written: false }\n  const tail =\n    target.length === 0\n      ? ''\n      : target.endsWith('\\n\\n')\n        ? ''\n        : target.endsWith('\\n')\n          ? '\\n'\n          : '\\n\\n'\n  return { next: target + tail + CLAUDE_IMPORT_LINE + '\\n', written: true }\n}\n\nfunction readOrEmpty(path: string): string {\n  return existsSync(path) ? readFileSync(path, 'utf8') : ''\n}\n\nexport function runLlmExport(cwd: string = process.cwd()): LlmExportResult {\n  const block = buildManagedBlock()\n\n  const agentsMdPath = join(cwd, 'AGENTS.md')\n  writeFileSync(agentsMdPath, upsertManagedBlock(readOrEmpty(agentsMdPath), block), 'utf8')\n\n  const claudeMdPath = join(cwd, 'CLAUDE.md')\n  const { next: claudeAfter, written: claudeImportWritten } = upsertClaudeImport(\n    readOrEmpty(claudeMdPath),\n  )\n  writeFileSync(claudeMdPath, claudeAfter, 'utf8')\n\n  return {\n    agentsMdPath,\n    claudeMdPath,\n    managedBlockBytes: block.length,\n    claudeImportWritten,\n  }\n}\n","#!/usr/bin/env node\n// The SDK's single bin (Stripe multi-subcommand pattern). Today the only\n// subcommand is `llm-export`, the consumer-facing agent-docs injector —\n// so an npm-only consumer runs `npx @alvera-ai/platform-sdk llm-export`\n// with no brew CLI install (architecture-decisions §2.10.13). The bin is\n// the ONLY thing reversed from inv #21; the SDK stays sub-export-less and\n// declares no postinstall.\nimport { runLlmExport } from '../llm-export.js'\n\nfunction usage(): void {\n  process.stderr.write(\n    'Usage: npx @alvera-ai/platform-sdk <command>\\n\\n' +\n      'Commands:\\n' +\n      '  llm-export    Write a managed AGENTS.md block pointing at the\\n' +\n      '                SDK agent-docs corpus in node_modules; ensure\\n' +\n      '                CLAUDE.md imports AGENTS.md. Idempotent.\\n',\n  )\n}\n\nfunction main(): void {\n  const command = process.argv[2]\n\n  if (command === undefined || command === '--help' || command === '-h') {\n    usage()\n    process.exit(command === undefined ? 1 : 0)\n  }\n\n  if (command === 'llm-export') {\n    try {\n      const result = runLlmExport(process.cwd())\n      process.stderr.write(\n        `✓ ${result.agentsMdPath} (${result.managedBlockBytes} bytes in managed block)\\n`,\n      )\n      process.stderr.write(\n        `✓ ${result.claudeMdPath}` +\n          `${result.claudeImportWritten ? ' (added @AGENTS.md import)' : ' (@AGENTS.md import already present)'}\\n`,\n      )\n      return\n    } catch (err) {\n      process.stderr.write(`llm-export failed: ${err instanceof Error ? err.message : String(err)}\\n`)\n      process.exit(1)\n    }\n  }\n\n  process.stderr.write(`unknown command \"${command}\".\\n\\n`)\n  usage()\n  process.exit(1)\n}\n\nmain()\n"],"mappings":";;;;;AAoBA,MAAM,eAAe;AACrB,MAAM,aAAa;AACnB,MAAM,qBAAqB;AAC3B,MAAM,mBAAmB;AAWzB,SAAgB,oBAA4B;CAC1C,MAAM,SAAS,gBAAgB,iBAAiB;AA6BhD,QA5BwB;EACtB;EACA;EACA;EACA;EACA;EACA,QAAQ,iBAAiB;EACzB;EACA;EACA;EACA;EACA,IAAI,OAAO;EACX;EACA,iCAAiC,OAAO;EACxC;EACA;EACA;EACA;EACA,kDAAkD,OAAO;EACzD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CACY,KAAK,KAAK;;AAGzB,SAAgB,mBAAmB,QAAgB,OAAuB;CACxE,MAAM,WAAW,OAAO,QAAQ,aAAa;CAC7C,MAAM,SAAS,OAAO,QAAQ,WAAW;AAEzC,KAAI,aAAa,MAAM,WAAW,GAShC,QAAO,UAPL,OAAO,WAAW,IACd,KACA,OAAO,SAAS,OAAO,GACrB,KACA,OAAO,SAAS,KAAK,GACnB,OACA,UACa,QAAQ;AAGjC,KAAI,aAAa,MAAM,WAAW,MAAM,SAAS,SAC/C,OAAM,IAAI,MACR,0DACe,SAAS,WAAW,OAAO,gEAE3C;CAGH,MAAM,SAAS,OAAO,MAAM,GAAG,SAAS;CACxC,MAAM,QAAQ,OAAO,MAAM,SAAS,GAAkB;AACtD,QAAO,SAAS,QAAQ;;AAG1B,SAAgB,mBAAmB,QAAoD;AAErF,KADgB,OAAO,MAAM,KAAK,CAAC,MAAM,SAAS,KAAK,MAAM,KAAK,mBAAmB,CACxE,QAAO;EAAE,MAAM;EAAQ,SAAS;EAAO;AASpD,QAAO;EAAE,MAAM,UAPb,OAAO,WAAW,IACd,KACA,OAAO,SAAS,OAAO,GACrB,KACA,OAAO,SAAS,KAAK,GACnB,OACA,UACqB,qBAAqB;EAAM,SAAS;EAAM;;AAG3E,SAAS,YAAY,MAAsB;AACzC,QAAO,WAAW,KAAK,GAAG,aAAa,MAAM,OAAO,GAAG;;AAGzD,SAAgB,aAAa,MAAc,QAAQ,KAAK,EAAmB;CACzE,MAAM,QAAQ,mBAAmB;CAEjC,MAAM,eAAe,KAAK,KAAK,YAAY;AAC3C,eAAc,cAAc,mBAAmB,YAAY,aAAa,EAAE,MAAM,EAAE,OAAO;CAEzF,MAAM,eAAe,KAAK,KAAK,YAAY;CAC3C,MAAM,EAAE,MAAM,aAAa,SAAS,wBAAwB,mBAC1D,YAAY,aAAa,CAC1B;AACD,eAAc,cAAc,aAAa,OAAO;AAEhD,QAAO;EACL;EACA;EACA,mBAAmB,MAAM;EACzB;EACD;;;;;AC1HH,SAAS,QAAc;AACrB,SAAQ,OAAO,MACb,wPAKD;;AAGH,SAAS,OAAa;CACpB,MAAM,UAAU,QAAQ,KAAK;AAE7B,KAAI,YAAY,UAAa,YAAY,YAAY,YAAY,MAAM;AACrE,SAAO;AACP,UAAQ,KAAK,YAAY,SAAY,IAAI,EAAE;;AAG7C,KAAI,YAAY,aACd,KAAI;EACF,MAAM,SAAS,aAAa,QAAQ,KAAK,CAAC;AAC1C,UAAQ,OAAO,MACb,KAAK,OAAO,aAAa,IAAI,OAAO,kBAAkB,4BACvD;AACD,UAAQ,OAAO,MACb,KAAK,OAAO,eACP,OAAO,sBAAsB,+BAA+B,uCAAuC,IACzG;AACD;UACO,KAAK;AACZ,UAAQ,OAAO,MAAM,sBAAsB,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,CAAC,IAAI;AAChG,UAAQ,KAAK,EAAE;;AAInB,SAAQ,OAAO,MAAM,oBAAoB,QAAQ,QAAQ;AACzD,QAAO;AACP,SAAQ,KAAK,EAAE;;AAGjB,MAAM"}