@secondlayer/cli 3.5.6 → 3.6.0

package/dist/cli.js

@@ -32439,7 +32439,7 @@ var {
 // package.json
 var package_default = {
   name: "@secondlayer/cli",
-  version: "3.5.6",
+  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);
 }
@@ -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}"...`);
@@ -36638,5 +36792,5 @@ registerLocalCommand(program);
 registerAccountCommand(program);
 program.parse();
 
-//# debugId=CA129D1D7E8ADE9A64756E2164756E21
+//# debugId=9B4F6BACEC00400164756E2164756E21
 //# sourceMappingURL=cli.js.map