@secondlayer/cli 3.5.6 → 3.6.1

package/README.md

@@ -25,6 +25,7 @@ sl instance create --plan hobby
 sl subgraphs scaffold SP1234ABCD.my-contract -o subgraphs/my-contract.ts
 sl subgraphs deploy subgraphs/my-contract.ts --start-block <recent-block>
 sl subgraphs query my-contract <table> --sort _block_height --order desc
+sl subgraphs spec my-contract --format openapi -o openapi.json
 ```
 
 `sl subgraphs scaffold` writes the definition file, creates or updates
@@ -128,6 +129,8 @@ invocation. No long-lived key on disk.
 | `sl subgraphs list` | List deployed subgraphs |
 | `sl subgraphs status <name>` | Indexing progress, row counts, gaps |
 | `sl subgraphs query <name> <table>` | Query a subgraph table with filters, sort, pagination |
+| `sl subgraphs spec <name> [--format openapi\|agent\|markdown] [-o <path>] [--server <url>]` | Export generated API docs for a deployed subgraph |
+| `sl subgraphs inspect <file> [--format openapi\|agent\|markdown] [-o <path>] [--server <url>]` | Generate API docs from a local `defineSubgraph()` file before deploy |
 | `sl subgraphs reindex <name>` | Drop + re-process from the tip backwards |
 | `sl subgraphs backfill <name>` | Fill a specific block range |
 | `sl subgraphs stop <name>` | Pause processing |
@@ -136,6 +139,32 @@ invocation. No long-lived key on disk.
 | `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 |
 
+#### Subgraph API specs
+
+Use `spec` when the subgraph is already deployed to the active project
+instance. Use `inspect` when you want the same documentation contract from a
+local TypeScript definition before deploy.
+
+```bash
+# Deployed subgraph docs from the active project instance
+sl subgraphs spec token-transfers --format openapi -o openapi.json
+sl subgraphs spec token-transfers --format agent
+sl subgraphs spec token-transfers --format markdown -o API.md
+
+# Local pre-deploy docs from a defineSubgraph() file
+sl subgraphs inspect subgraphs/token-transfers.ts --format agent
+sl subgraphs inspect subgraphs/token-transfers.ts --format openapi \
+  --server https://<your-slug>.secondlayer.tools
+```
+
+Formats:
+
+| Format | Use |
+|---|---|
+| `openapi` | OpenAPI 3.1 JSON for docs tooling, client generators, and API catalogs |
+| `agent` | Compact JSON schema for agents that need table, column, filter, and endpoint context |
+| `markdown` | Human-readable API reference for docs pages or repository docs |
+
 ### Local dev + OSS
 
 | Command | What it does |

package/dist/cli.js

@@ -32439,7 +32439,7 @@ var {
 // package.json
 var package_default = {
   name: "@secondlayer/cli",
-  version: "3.5.6",
+  version: "3.6.1",
   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);
 }
@@ -34599,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 = [
@@ -35003,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}"...`);
@@ -36487,6 +36641,11 @@ function handleInstanceError(err, action) {
       error("This project already has an instance. Run `sl instance info` to see it.");
       process.exit(1);
     }
+    if (err.code === "PROVISIONER_REJECTED" || err.code === "INSTANCE_RECORD_FAILED" || err.code === "INSTANCE_PROVISION_FAILED") {
+      error(err.message || `Failed to ${action}.`);
+      error("Run: sl instance info before retrying.");
+      process.exit(1);
+    }
     error(err.message || `Failed to ${action}.`);
     process.exit(1);
   }
@@ -36638,5 +36797,5 @@ registerLocalCommand(program);
 registerAccountCommand(program);
 program.parse();
 
-//# debugId=CA129D1D7E8ADE9A64756E2164756E21
+//# debugId=EA9BC913F2D4968D64756E2164756E21
 //# sourceMappingURL=cli.js.map