@depctdev/depct 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@depctdev/depct",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI for running Node apps with Depct instrumentation",
   "bin": {
     "depct": "src/index.cjs"
@@ -12,6 +12,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "depct-loader": "0.1.0"
+    "depct-loader": "0.1.0",
+    "fast-glob": "^3.3.3"
   }
 }

package/src/index.cjs

@@ -2,20 +2,26 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const zlib = require("node:zlib");
 const { spawn } = require("node:child_process");
 
 const HELP = `depct CLI
 
 Usage:
-  depct run [options] -- <command> [args...]
-  depct run [options] <command> [args...]
+  depct init [options]                       Register a new project
+  depct run [options] -- <command> [args...] Run with instrumentation
+  depct generate [options]                   Generate documentation
 
-Examples:
-  depct run -- node server.js
-  depct run --project-id my-api --server-url http://localhost:3100 -- node server.js
-  depct run --no-debug-events -- node server.js
+Commands:
+  init        Register project with the depct server and create .depctrc
+  run         Run a command with depct instrumentation
+  generate    Package source files, trigger doc generation, poll for completion
 
-Options:
+depct init options:
+  --name <name>                  Project name (default: from package.json)
+  --server-url <url>             Server URL (default: DEPCT_SERVER_URL or http://localhost:3100)
+
+depct run options:
   --project-root <path>          Set DEPCT_PROJECT_ROOT (default: current directory)
   --project-id <id>              Set DEPCT_PROJECT_ID
   --server-url <url>             Set DEPCT_SERVER_URL
@@ -26,6 +32,11 @@ Options:
   --debug / --no-debug           Set DEPCT_DEBUG (default: true)
   --debug-events / --no-debug-events
                                  Set DEPCT_DEBUG_EVENTS (default: true)
+
+depct generate options:
+  --server-url <url>             Server URL override
+
+Global:
   -h, --help                     Show help
 `;
 
@@ -196,19 +207,229 @@ function applyEnvOptions(baseEnv, options) {
   return env;
 }
 
-function run(argv) {
-  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
-    printHelp(0);
+// ── .depctrc ──
+
+const DEPCTRC_NAME = ".depctrc";
+const DEFAULT_INCLUDE = ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx", "**/*.cjs", "**/*.mjs"];
+const DEFAULT_EXCLUDE = ["node_modules/**", "dist/**", ".git/**", "coverage/**", ".next/**", "build/**"];
+
+function readDepctrc() {
+  const rcPath = path.resolve(process.cwd(), DEPCTRC_NAME);
+  if (!fs.existsSync(rcPath)) {
+    fail(`No ${DEPCTRC_NAME} found. Run \`depct init\` first.`);
   }
+  const raw = fs.readFileSync(rcPath, "utf8");
+  const config = JSON.parse(raw);
+  return {
+    project_id: config.project_id,
+    project_name: config.project_name || "",
+    server_url: config.server_url || process.env.DEPCT_SERVER_URL || "http://localhost:3100",
+    include: config.include || DEFAULT_INCLUDE,
+    exclude: config.exclude || DEFAULT_EXCLUDE,
+  };
+}
 
-  const commandName = argv[0];
-  if (commandName !== "run") {
-    fail(`Unknown command: ${commandName}`);
+function writeDepctrc(config) {
+  const rcPath = path.resolve(process.cwd(), DEPCTRC_NAME);
+  fs.writeFileSync(rcPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+// ── depct init ──
+
+function parseInitArgs(argv) {
+  const options = { name: "", serverUrl: "" };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+    if (arg === "--name" && next) { options.name = next; i++; }
+    else if (arg === "--server-url" && next) { options.serverUrl = next; i++; }
+    else if (arg === "-h" || arg === "--help") printHelp(0);
+  }
+  return options;
+}
+
+async function handleInit(argv) {
+  const options = parseInitArgs(argv);
+  const serverUrl = options.serverUrl || process.env.DEPCT_SERVER_URL || "http://localhost:3100";
+  const projectName = options.name || inferProjectIdFromPackageJson(process.cwd()) || path.basename(process.cwd());
+
+  process.stdout.write(`Registering project "${projectName}" with ${serverUrl}...\n`);
+
+  let response;
+  try {
+    response = await fetch(`${serverUrl}/v1/projects`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ project_name: projectName }),
+    });
+  } catch (err) {
+    fail(`Failed to connect to server at ${serverUrl}: ${err.message}`);
+  }
+
+  const result = await response.json();
+  if (!result.ok) {
+    fail(`Server error: ${result.error}`);
+  }
+
+  const config = {
+    project_id: result.project_id,
+    project_name: result.project_name,
+    server_url: serverUrl,
+    include: DEFAULT_INCLUDE,
+    exclude: DEFAULT_EXCLUDE,
+  };
+
+  writeDepctrc(config);
+
+  process.stdout.write(`Project registered: ${result.project_id}\n`);
+  process.stdout.write(`Config written to ${DEPCTRC_NAME}\n`);
+}
+
+// ── depct generate ──
+
+function parseGenerateArgs(argv) {
+  const options = { serverUrl: "" };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+    if (arg === "--server-url" && next) { options.serverUrl = next; i++; }
+    else if (arg === "-h" || arg === "--help") printHelp(0);
+  }
+  return options;
+}
+
+async function packageSourceFiles(include, exclude) {
+  const fg = require("fast-glob");
+  const files = await fg(include, {
+    cwd: process.cwd(),
+    ignore: exclude,
+    absolute: true,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+  });
+
+  if (files.length === 0) {
+    fail("No source files matched the include/exclude patterns in .depctrc");
+  }
+
+  const parts = [];
+  for (const filePath of files) {
+    const relativePath = path.relative(process.cwd(), filePath);
+    const content = fs.readFileSync(filePath, "utf8");
+    parts.push(`===== ${relativePath} =====\n${content}`);
+  }
+
+  process.stdout.write(`Packaged ${files.length} source files\n`);
+  return parts.join("\n\n");
+}
+
+async function pollGenerationStatus(serverUrl, genId) {
+  const maxWaitMs = 300000;
+  const pollInterval = 3000;
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < maxWaitMs) {
+    let response;
+    try {
+      response = await fetch(`${serverUrl}/v1/generate/${genId}/status`);
+    } catch {
+      process.stdout.write(".");
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+      continue;
+    }
+
+    const result = await response.json();
+
+    if (result.status === "complete") {
+      process.stdout.write("\nGeneration complete.\n");
+      return;
+    }
+    if (result.status === "failed") {
+      fail("Generation failed on the server.");
+    }
+
+    process.stdout.write(".");
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
   }
 
-  const { options, command } = parseRunArgs(argv.slice(1));
+  fail("Generation timed out after 5 minutes. Check server logs.");
+}
+
+async function handleGenerate(argv) {
+  const options = parseGenerateArgs(argv);
+  const config = readDepctrc();
+  const serverUrl = options.serverUrl || config.server_url;
+
+  process.stdout.write(`Packaging source files for project ${config.project_id}...\n`);
+  const sourceFiles = await packageSourceFiles(config.include, config.exclude);
+
+  const payload = JSON.stringify({
+    source_files: sourceFiles,
+    project_name: config.project_name,
+  });
+
+  const compressed = zlib.gzipSync(Buffer.from(payload, "utf8"));
+
+  process.stdout.write(`Sending ${(compressed.length / 1024).toFixed(1)} KB (gzip) to ${serverUrl}...\n`);
+
+  let response;
+  try {
+    response = await fetch(`${serverUrl}/v1/generate/${config.project_id}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "content-encoding": "gzip",
+      },
+      body: compressed,
+    });
+  } catch (err) {
+    fail(`Failed to connect to server: ${err.message}`);
+  }
+
+  const result = await response.json();
+
+  if (!result.ok) {
+    if (result.cached) {
+      process.stdout.write(`No new events since last generation. Using cached result (generation ${result.generation_id}).\n`);
+      return;
+    }
+    fail(`Server error (${response.status}): ${result.error}`);
+  }
+
+  if (result.cached) {
+    process.stdout.write(`No new events since last generation. Using cached result (generation ${result.generation_id}).\n`);
+    return;
+  }
+
+  const genId = result.generation_id;
+  process.stdout.write(`Generation started (ID: ${genId}). Waiting for completion`);
+
+  await pollGenerationStatus(serverUrl, genId);
+}
+
+// ── depct run ──
+
+function handleRun(argv) {
+  const { options, command } = parseRunArgs(argv);
   const [execPath, ...execArgs] = command;
   const loaderEntry = resolveLoaderEntry();
+
+  // If .depctrc exists, use its project_id and server_url
+  const rcPath = path.resolve(process.cwd(), DEPCTRC_NAME);
+  if (fs.existsSync(rcPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(rcPath, "utf8"));
+      if (config.project_id && !options.projectId) {
+        options.projectId = config.project_id;
+      }
+      if (config.server_url && !options.serverUrl) {
+        options.serverUrl = config.server_url;
+      }
+    } catch {
+      // ignore parse errors
+    }
+  }
+
   const env = applyEnvOptions(process.env, options);
   env.NODE_OPTIONS = withNodeOptions(env.NODE_OPTIONS, loaderEntry);
 
@@ -232,4 +453,35 @@ function run(argv) {
   });
 }
 
+// ── main dispatch ──
+
+function run(argv) {
+  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+    printHelp(0);
+  }
+
+  const commandName = argv[0];
+
+  if (commandName === "run") {
+    handleRun(argv.slice(1));
+    return;
+  }
+
+  if (commandName === "init") {
+    handleInit(argv.slice(1)).catch((err) => {
+      fail(err.message || String(err));
+    });
+    return;
+  }
+
+  if (commandName === "generate") {
+    handleGenerate(argv.slice(1)).catch((err) => {
+      fail(err.message || String(err));
+    });
+    return;
+  }
+
+  fail(`Unknown command: ${commandName}`);
+}
+
 run(process.argv.slice(2));