@secondlayer/cli 3.5.5 → 3.6.0

package/README.md

@@ -27,6 +27,11 @@ sl subgraphs deploy subgraphs/my-contract.ts --start-block <recent-block>
 sl subgraphs query my-contract <table> --sort _block_height --order desc
 ```
 
+`sl subgraphs scaffold` writes the definition file, creates or updates
+`package.json`, and runs `bun install` by default so the generated import is
+deployable immediately. Pass `--no-install` to skip the install and run
+`bun install` manually in the output directory.
+
 Then wire a receiver:
 
 ```bash
@@ -128,7 +133,7 @@ invocation. No long-lived key on disk.
 | `sl subgraphs stop <name>` | Pause processing |
 | `sl subgraphs gaps <name>` | List missing block ranges |
 | `sl subgraphs delete <name>` | Drop the subgraph + its schema |
-| `sl subgraphs scaffold <SP...::contract>` | Generate a starter subgraph from a deployed contract |
+| `sl subgraphs scaffold <SP...::contract> [-o <path>] [--no-install]` | Generate a starter subgraph from a deployed contract, write/amend `package.json`, and install dependencies unless skipped |
 | `sl subgraphs generate <name>` | Regenerate TS types for an existing subgraph |
 
 ### Local dev + OSS

package/dist/cli.js

@@ -26406,7 +26406,7 @@ var require_cross_spawn = __commonJS((exports, module) => {
   var cp = __require("child_process");
   var parse2 = require_parse3();
   var enoent = require_enoent();
-  function spawn(command, args, options3) {
+  function spawn2(command, args, options3) {
     const parsed = parse2(command, args, options3);
     const spawned = cp.spawn(parsed.command, parsed.args, parsed.options);
     enoent.hookChildProcess(spawned, parsed);
@@ -26418,8 +26418,8 @@ var require_cross_spawn = __commonJS((exports, module) => {
     result.error = result.error || enoent.verifyENOENTSync(result.status, parsed);
     return result;
   }
-  module.exports = spawn;
-  module.exports.spawn = spawn;
+  module.exports = spawn2;
+  module.exports.spawn = spawn2;
   module.exports.sync = spawnSync;
   module.exports._parse = parse2;
   module.exports._enoent = enoent;
@@ -31750,7 +31750,7 @@ var init_promise = __esm(() => {
 
 // ../../node_modules/execa/lib/methods/main-async.js
 import { setMaxListeners } from "node:events";
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 var execaCoreAsync = (rawFile, rawArguments, rawOptions, createNested) => {
   const { file, commandArguments, command, escapedCommand, startTime, verboseInfo, options: options3, fileDescriptors } = handleAsyncArguments(rawFile, rawArguments, rawOptions);
   const { subprocess, promise } = spawnSubprocessAsync({
@@ -31795,7 +31795,7 @@ var execaCoreAsync = (rawFile, rawArguments, rawOptions, createNested) => {
 }, spawnSubprocessAsync = ({ file, commandArguments, options: options3, startTime, verboseInfo, command, escapedCommand, fileDescriptors }) => {
   let subprocess;
   try {
-    subprocess = spawn(...concatenateShell(file, commandArguments, options3));
+    subprocess = spawn2(...concatenateShell(file, commandArguments, options3));
   } catch (error2) {
     return handleEarlyError({
       error: error2,
@@ -32439,7 +32439,7 @@ var {
 // package.json
 var package_default = {
   name: "@secondlayer/cli",
-  version: "3.5.5",
+  version: "3.6.0",
   description: "CLI for subgraphs and blockchain indexing on Stacks",
   type: "module",
   bin: {
@@ -32482,8 +32482,8 @@ var package_default = {
   dependencies: {
     "@inquirer/prompts": "^8.2.0",
     "@secondlayer/bundler": "^0.3.2",
-    "@secondlayer/sdk": "^3.2.2",
-    "@secondlayer/shared": "^4.3.4",
+    "@secondlayer/sdk": "^3.3.0",
+    "@secondlayer/shared": "^4.4.0",
     "@secondlayer/stacks": "^2.0.0",
     "@secondlayer/subgraphs": "^1.3.2",
     "@biomejs/js-api": "^0.7.0",
@@ -32555,6 +32555,15 @@ async function listSubgraphsApi() {
 async function getSubgraphApi(name) {
   return (await getTenantClient()).subgraphs.get(name);
 }
+async function getSubgraphOpenApi(name, options) {
+  return (await getTenantClient()).subgraphs.openapi(name, options);
+}
+async function getSubgraphAgentSchema(name, options) {
+  return (await getTenantClient()).subgraphs.schema(name, options);
+}
+async function getSubgraphMarkdown(name, options) {
+  return (await getTenantClient()).subgraphs.markdown(name, options);
+}
 async function reindexSubgraphApi(name, options) {
   return (await getTenantClient()).subgraphs.reindex(name, options);
 }
@@ -34315,6 +34324,7 @@ async function resyncDatabase(skipConfirm, backfill) {
   }
 }
 // src/commands/subgraphs.ts
+import { spawn } from "node:child_process";
 import {
   existsSync as existsSync3,
   mkdirSync as mkdirSync2,
@@ -34598,6 +34608,91 @@ function parseStartBlockOption(value) {
   }
   return parsed;
 }
+function parseSubgraphSpecFormat(value) {
+  const format = value ?? "openapi";
+  if (format === "openapi" || format === "agent" || format === "markdown") {
+    return format;
+  }
+  throw new Error("--format must be one of: openapi, agent, markdown");
+}
+function formatSubgraphSpecOutput(spec, format) {
+  if (typeof spec === "string")
+    return spec;
+  if (format === "markdown")
+    return String(spec);
+  return `${JSON.stringify(spec, null, 2)}
+`;
+}
+async function writeOrPrintSubgraphSpec(spec, format, output) {
+  const text = formatSubgraphSpecOutput(spec, format);
+  if (!output) {
+    process.stdout.write(text);
+    return;
+  }
+  const outPath = resolve3(output);
+  const dir = resolve3(outPath, "..");
+  if (!existsSync3(dir))
+    mkdirSync2(dir, { recursive: true });
+  await writeTextFile(outPath, text);
+  success(`Created ${outPath}`);
+}
+function createLocalSubgraphDetail(input2) {
+  const tables = {};
+  for (const [tableName, rawTable] of Object.entries(input2.schema)) {
+    const table = rawTable;
+    const columns = {};
+    for (const [columnName, column] of Object.entries(table.columns ?? {})) {
+      columns[columnName] = {
+        type: column.type ?? "text",
+        ...column.nullable && { nullable: true },
+        ...column.indexed && { indexed: true },
+        ...column.search && { searchable: true },
+        ...column.default !== undefined && { default: column.default }
+      };
+    }
+    columns._id = { type: "serial" };
+    columns._block_height = { type: "bigint" };
+    columns._tx_id = { type: "text" };
+    columns._created_at = { type: "timestamp" };
+    tables[tableName] = {
+      endpoint: `/subgraphs/${input2.name}/${tableName}`,
+      columns,
+      rowCount: 0,
+      example: `/subgraphs/${input2.name}/${tableName}?_sort=_block_height&_order=desc&_limit=10`,
+      ...table.indexes && { indexes: table.indexes },
+      ...table.uniqueKeys && { uniqueKeys: table.uniqueKeys }
+    };
+  }
+  return {
+    name: input2.name,
+    version: input2.version ?? "0.0.0",
+    schemaHash: input2.schemaHash,
+    status: "local",
+    lastProcessedBlock: 0,
+    ...input2.description && { description: input2.description },
+    sources: input2.sources,
+    health: {
+      totalProcessed: 0,
+      totalErrors: 0,
+      errorRate: 0,
+      lastError: null,
+      lastErrorAt: null
+    },
+    sync: {
+      status: "synced",
+      startBlock: 0,
+      lastProcessedBlock: 0,
+      chainTip: 0,
+      blocksRemaining: 0,
+      progress: 1,
+      gaps: { count: 0, totalMissingBlocks: 0, ranges: [] },
+      integrity: "complete"
+    },
+    tables,
+    createdAt: new Date(0).toISOString(),
+    updatedAt: new Date(0).toISOString()
+  };
+}
 function readCliSubgraphsDependency() {
   const here = dirname4(fileURLToPath2(import.meta.url));
   const candidates = [
@@ -34638,15 +34733,24 @@ function ensureScaffoldPackageJson(dir) {
 `, "utf8");
 }
 async function runBunInstall(dir) {
-  const proc = Bun.spawn(["bun", "install"], {
-    cwd: dir,
-    stdout: "inherit",
-    stderr: "inherit"
+  await new Promise((resolvePromise, reject) => {
+    const proc = spawn("bun", ["install"], {
+      cwd: dir,
+      stdio: "inherit"
+    });
+    proc.on("error", reject);
+    proc.on("close", (exitCode, signal) => {
+      if (exitCode === 0) {
+        resolvePromise();
+        return;
+      }
+      if (exitCode !== null) {
+        reject(new Error(`bun install exited with code ${exitCode}`));
+        return;
+      }
+      reject(new Error(`bun install exited with signal ${signal}`));
+    });
   });
-  const exitCode = await proc.exited;
-  if (exitCode !== 0) {
-    throw new Error(`bun install exited with code ${exitCode}`);
-  }
 }
 async function installScaffoldDependencies(dir, options2 = {}) {
   if (options2.install === false)
@@ -34993,6 +35097,66 @@ Table endpoints:`));
       handleApiError(err, "get subgraph status");
     }
   });
+  subgraphs.command("spec <name>").description("Output API documentation for a deployed subgraph").option("--format <format>", "Output format: openapi, agent, markdown", "openapi").option("-o, --output <path>", "Write output to a file").option("--server <url>", "Override the server URL in generated docs").action(async (name, options2) => {
+    try {
+      const format = parseSubgraphSpecFormat(options2.format);
+      const specOptions = options2.server ? { serverUrl: options2.server } : undefined;
+      const spec = format === "openapi" ? await getSubgraphOpenApi(name, specOptions) : format === "agent" ? await getSubgraphAgentSchema(name, specOptions) : await getSubgraphMarkdown(name, specOptions);
+      await writeOrPrintSubgraphSpec(spec, format, options2.output);
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("--format")) {
+        error(err.message);
+        process.exit(1);
+      }
+      handleApiError(err, "generate subgraph spec");
+    }
+  });
+  subgraphs.command("inspect <file>").description("Output API documentation for a local subgraph file").option("--format <format>", "Output format: openapi, agent, markdown", "agent").option("-o, --output <path>", "Write output to a file").option("--server <url>", "Override the server URL in generated docs").action(async (file, options2) => {
+    try {
+      const format = parseSubgraphSpecFormat(options2.format);
+      const absPath = resolve3(file);
+      if (!existsSync3(absPath)) {
+        error(`File not found: ${absPath}`);
+        process.exit(1);
+      }
+      const { readFile: readFile4 } = await import("node:fs/promises");
+      const { bundleSubgraphCode } = await import("@secondlayer/bundler");
+      const { generateSubgraphSQL } = await import("@secondlayer/subgraphs");
+      const {
+        generateSubgraphAgentSchema,
+        generateSubgraphMarkdown,
+        generateSubgraphOpenApi
+      } = await import("@secondlayer/shared/subgraphs/spec");
+      const source = await readFile4(absPath, "utf8");
+      const bundled = await bundleSubgraphCode(source);
+      const { hash } = generateSubgraphSQL({
+        name: bundled.name,
+        version: bundled.version,
+        description: bundled.description,
+        sources: bundled.sources,
+        schema: bundled.schema,
+        handlers: {}
+      });
+      const detail = createLocalSubgraphDetail({
+        name: bundled.name,
+        version: bundled.version,
+        description: bundled.description,
+        sources: bundled.sources,
+        schema: bundled.schema,
+        schemaHash: hash
+      });
+      const specOptions = options2.server ? { serverUrl: options2.server } : undefined;
+      const spec = format === "openapi" ? generateSubgraphOpenApi(detail, specOptions) : format === "agent" ? generateSubgraphAgentSchema(detail, specOptions) : generateSubgraphMarkdown(detail, specOptions);
+      await writeOrPrintSubgraphSpec(spec, format, options2.output);
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("--format")) {
+        error(err.message);
+        process.exit(1);
+      }
+      error(`Failed to inspect subgraph: ${err}`);
+      process.exit(1);
+    }
+  });
   subgraphs.command("reindex <name>").description("Reindex a subgraph from historical blocks").option("--from <block>", "Start block height").option("--to <block>", "End block height").action(async (name, options2) => {
     try {
       info(`Reindexing subgraph "${name}"...`);
@@ -36628,5 +36792,5 @@ registerLocalCommand(program);
 registerAccountCommand(program);
 program.parse();
 
-//# debugId=3944D78DF47F7DD164756E2164756E21
+//# debugId=9B4F6BACEC00400164756E2164756E21
 //# sourceMappingURL=cli.js.map