sentinelayer-cli 0.1.0

package/src/commands/plugin.js

@@ -0,0 +1,260 @@
+import path from "node:path";
+import process from "node:process";
+
+import pc from "picocolors";
+
+import {
+  buildPluginManifestTemplate,
+  computePluginLoadOrder,
+  listPluginManifests,
+  normalizePluginId,
+  normalizePluginLoadStage,
+  normalizePluginPackType,
+  PLUGIN_LOAD_STAGES,
+  PLUGIN_PACK_TYPES,
+  readJsonFile,
+  resolveDefaultPluginManifestPath,
+  summarizePluginValidationError,
+  validatePluginManifest,
+  writeJsonFile,
+} from "../plugin/manifest.js";
+
+function shouldEmitJson(options, command) {
+  const local = Boolean(options && options.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+function normalizeOutputPath(rawValue, fallbackPath) {
+  const candidate = String(rawValue || "").trim();
+  if (!candidate) {
+    return fallbackPath;
+  }
+  return path.resolve(process.cwd(), candidate);
+}
+
+export function registerPluginCommand(program) {
+  const plugin = program
+    .command("plugin")
+    .description("Manage Sentinelayer plugin manifests and extension-pack contracts");
+
+  plugin
+    .command("init")
+    .description("Initialize a deterministic plugin manifest scaffold")
+    .requiredOption("--id <plugin-id>", "Unique plugin id (lowercase)")
+    .option(
+      "--pack-type <type>",
+      `Pack boundary type (${PLUGIN_PACK_TYPES.join("|")})`,
+      "plugin"
+    )
+    .option(
+      "--stage <stage>",
+      `Load-order stage (${PLUGIN_LOAD_STAGES.join("|")})`,
+      "scan"
+    )
+    .option("--path <path>", "Destination file path override")
+    .option("--output-dir <path>", "Optional artifact output root override")
+    .option("--force", "Overwrite destination file if it already exists")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const pluginId = normalizePluginId(options.id);
+      const packType = normalizePluginPackType(options.packType);
+      const stage = normalizePluginLoadStage(options.stage);
+      const defaultPath = await resolveDefaultPluginManifestPath({
+        cwd: process.cwd(),
+        outputDir: options.outputDir,
+        env: process.env,
+        pluginId,
+      });
+      const outputPath = normalizeOutputPath(options.path, defaultPath);
+      const template = buildPluginManifestTemplate({
+        pluginId,
+        packType,
+        stage,
+      });
+      const manifest = validatePluginManifest(template);
+      const writtenPath = await writeJsonFile(outputPath, manifest, { force: Boolean(options.force) });
+
+      const payload = {
+        command: "plugin init",
+        pluginId,
+        packType: manifest.pack_type,
+        stage: manifest.load_order.stage,
+        outputPath: writtenPath,
+        schemaVersion: manifest.schema_version,
+        kind: manifest.kind,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.green(`Wrote plugin manifest: ${writtenPath}`));
+      console.log(pc.gray(`Plugin id: ${pluginId}`));
+      console.log(pc.gray(`Pack type: ${manifest.pack_type}`));
+      console.log(pc.gray(`Stage: ${manifest.load_order.stage}`));
+      console.log(pc.gray("Next: edit capabilities/security/load_order and validate before use."));
+    });
+
+  plugin
+    .command("validate")
+    .description("Validate a plugin manifest against Sentinelayer contract")
+    .requiredOption("--file <path>", "Manifest file to validate")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const inputPath = path.resolve(process.cwd(), String(options.file || "").trim());
+      const loaded = await readJsonFile(inputPath);
+      try {
+        const manifest = validatePluginManifest(loaded.data);
+        const payload = {
+          command: "plugin validate",
+          valid: true,
+          filePath: loaded.path,
+          pluginId: manifest.id,
+          version: manifest.version,
+          packType: manifest.pack_type,
+          stage: manifest.load_order.stage,
+        };
+        if (shouldEmitJson(options, command)) {
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+
+        console.log(pc.green(`Manifest valid (${manifest.id}@${manifest.version})`));
+        console.log(pc.gray(`File: ${loaded.path}`));
+      } catch (error) {
+        const payload = {
+          command: "plugin validate",
+          valid: false,
+          filePath: loaded.path,
+          error: summarizePluginValidationError(error),
+        };
+        if (shouldEmitJson(options, command)) {
+          console.log(JSON.stringify(payload, null, 2));
+        } else {
+          console.log(pc.red(`Manifest invalid: ${payload.error}`));
+          console.log(pc.gray(`File: ${loaded.path}`));
+        }
+        process.exitCode = 2;
+      }
+    });
+
+  plugin
+    .command("list")
+    .description("List plugin manifests discovered under local artifact root")
+    .option("--path <path>", "Workspace path for config resolution", ".")
+    .option("--output-dir <path>", "Optional artifact output root override")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const listing = await listPluginManifests({
+        cwd: targetPath,
+        outputDir: options.outputDir,
+        env: process.env,
+      });
+
+      const payload = {
+        command: "plugin list",
+        pluginsRoot: listing.pluginsRoot,
+        pluginCount: listing.plugins.length,
+        invalidCount: listing.invalid.length,
+        plugins: listing.plugins,
+        invalid: listing.invalid,
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else {
+        console.log(pc.bold("Plugin manifests"));
+        console.log(pc.gray(`Root: ${listing.pluginsRoot}`));
+        if (!listing.plugins.length && !listing.invalid.length) {
+          console.log(pc.gray("(no plugin manifests found)"));
+          return;
+        }
+
+        for (const pluginEntry of listing.plugins) {
+          console.log(
+            `${pluginEntry.id}@${pluginEntry.version} | type=${pluginEntry.packType} | stage=${pluginEntry.stage} | commands=${pluginEntry.commandCount} | templates=${pluginEntry.templateCount} | policies=${pluginEntry.policyCount}`
+          );
+          console.log(pc.gray(`  ${pluginEntry.path}`));
+        }
+
+        for (const invalidEntry of listing.invalid) {
+          console.log(pc.yellow(`invalid manifest: ${invalidEntry.path}`));
+          console.log(pc.gray(`  ${invalidEntry.error}`));
+        }
+      }
+
+      if (listing.invalid.length > 0) {
+        process.exitCode = 2;
+      }
+    });
+
+  plugin
+    .command("order")
+    .description("Resolve deterministic plugin load order by stage")
+    .option("--path <path>", "Workspace path for config resolution", ".")
+    .option(
+      "--stage <stage>",
+      `Optional single-stage filter (${PLUGIN_LOAD_STAGES.join("|")})`
+    )
+    .option("--output-dir <path>", "Optional artifact output root override")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const stage = options.stage ? normalizePluginLoadStage(options.stage) : "";
+      const ordering = await computePluginLoadOrder({
+        cwd: targetPath,
+        outputDir: options.outputDir,
+        env: process.env,
+        stage,
+      });
+
+      const payload = {
+        command: "plugin order",
+        pluginsRoot: ordering.pluginsRoot,
+        invalidCount: ordering.invalidCount,
+        hasBlockingIssues: ordering.hasBlockingIssues,
+        stages: ordering.stages,
+        invalid: ordering.invalid,
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else {
+        console.log(pc.bold("Plugin load order"));
+        console.log(pc.gray(`Root: ${ordering.pluginsRoot}`));
+        for (const stageEntry of ordering.stages) {
+          console.log(
+            `${stageEntry.stage}: plugins=${stageEntry.pluginCount} cycle=${stageEntry.cycleDetected ? "yes" : "no"}`
+          );
+          if (stageEntry.order.length > 0) {
+            console.log(pc.gray(`  order: ${stageEntry.order.join(" -> ")}`));
+          }
+          if (stageEntry.unresolvedReferences.length > 0) {
+            for (const unresolved of stageEntry.unresolvedReferences) {
+              console.log(
+                pc.yellow(
+                  `  unresolved ${unresolved.relation}: ${unresolved.pluginId} -> ${unresolved.dependencyId}`
+                )
+              );
+            }
+          }
+          if (stageEntry.cycleNodes.length > 0) {
+            console.log(pc.red(`  cycle nodes: ${stageEntry.cycleNodes.join(", ")}`));
+          }
+        }
+        if (ordering.invalid.length > 0) {
+          for (const invalidEntry of ordering.invalid) {
+            console.log(pc.yellow(`invalid manifest: ${invalidEntry.path}`));
+            console.log(pc.gray(`  ${invalidEntry.error}`));
+          }
+        }
+      }
+
+      if (ordering.hasBlockingIssues) {
+        process.exitCode = 2;
+      }
+    });
+}

package/src/commands/policy.js

@@ -0,0 +1,132 @@
+import path from "node:path";
+import process from "node:process";
+
+import pc from "picocolors";
+
+import { setConfigValue } from "../config/service.js";
+import {
+  DEFAULT_POLICY_PACK_ID,
+  resolveActivePolicyPack,
+  resolvePolicyPackById,
+} from "../policy/packs.js";
+
+function shouldEmitJson(options, command) {
+  const local = Boolean(options && options.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+function normalizeScope(rawValue) {
+  const normalized = String(rawValue || "project").trim().toLowerCase();
+  if (normalized !== "project" && normalized !== "global") {
+    throw new Error("scope must be project or global.");
+  }
+  return normalized;
+}
+
+export function registerPolicyCommand(program) {
+  const policy = program.command("policy").description("Manage Sentinelayer policy packs");
+
+  policy
+    .command("list")
+    .description("List built-in and plugin-provided policy packs")
+    .option("--path <path>", "Workspace path for config/plugin resolution", ".")
+    .option("--output-dir <path>", "Optional artifact output root override")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const active = await resolveActivePolicyPack({
+        cwd: targetPath,
+        outputDir: options.outputDir,
+        env: process.env,
+      });
+
+      const payload = {
+        command: "policy list",
+        defaultPolicyPack: DEFAULT_POLICY_PACK_ID,
+        configuredPolicyPack: active.configuredId,
+        activePolicyPack: active.selected ? active.selected.id : null,
+        invalidManifestCount: active.listing.invalidManifestCount,
+        pluginRoot: active.listing.pluginsRoot,
+        packs: active.listing.packs.map((pack) => ({
+          id: pack.id,
+          name: pack.name,
+          source: pack.source,
+          description: pack.description,
+          scanProfile: pack.scanProfile,
+          plugin: pack.plugin || null,
+        })),
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.bold("Policy packs"));
+      console.log(pc.gray(`Active: ${payload.activePolicyPack || "(none)"}`));
+      for (const pack of payload.packs) {
+        const marker = pack.id === payload.activePolicyPack ? "*" : " ";
+        const source = pack.source === "plugin" ? "plugin" : "builtin";
+        console.log(`${marker} ${pack.id} (${source}) - ${pack.description}`);
+      }
+      if (payload.invalidManifestCount > 0) {
+        console.log(
+          pc.yellow(
+            `Detected ${payload.invalidManifestCount} invalid plugin manifest(s); run 'plugin list --json' for details.`
+          )
+        );
+      }
+    });
+
+  policy
+    .command("use <packId>")
+    .description("Set active policy pack in config (project/global scope)")
+    .option("--path <path>", "Workspace path for config/plugin resolution", ".")
+    .option("--output-dir <path>", "Optional artifact output root override")
+    .option("--scope <scope>", "Write scope (project|global)", "project")
+    .option("--json", "Emit machine-readable output")
+    .action(async (packId, options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const scope = normalizeScope(options.scope);
+      const resolution = await resolvePolicyPackById({
+        packId,
+        cwd: targetPath,
+        outputDir: options.outputDir,
+        env: process.env,
+      });
+
+      if (!resolution.selected) {
+        const available = resolution.packs.map((pack) => pack.id).sort((left, right) => left.localeCompare(right));
+        throw new Error(
+          `Unknown policy pack '${resolution.packId}'. Available: ${available.join(", ") || "(none)"}`
+        );
+      }
+
+      const writeResult = await setConfigValue({
+        key: "defaultPolicyPack",
+        value: resolution.selected.id,
+        scope,
+        cwd: targetPath,
+      });
+
+      const payload = {
+        command: "policy use",
+        selected: resolution.selected.id,
+        source: resolution.selected.source,
+        scope: writeResult.scope,
+        configPath: writeResult.path,
+        scanProfile: resolution.selected.scanProfile,
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.green(`Policy pack set to '${resolution.selected.id}' (${resolution.selected.source}).`));
+      console.log(pc.gray(`Scope: ${writeResult.scope}`));
+      console.log(pc.gray(`Config: ${writeResult.path}`));
+    });
+}

package/src/commands/prompt.js

@@ -0,0 +1,238 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import pc from "picocolors";
+
+import { formatIngestResolutionNotice, resolveCodebaseIngest } from "../ingest/engine.js";
+import {
+  defaultPromptFileName,
+  generateExecutionPrompt,
+  resolvePromptTarget,
+  SUPPORTED_PROMPT_TARGETS,
+} from "../prompt/generator.js";
+import { renderTerminalMarkdown } from "../ui/markdown.js";
+
+function shouldEmitJson(options, command) {
+  const local = Boolean(options && options.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+function resolveSpecPath(targetPath, explicitSpecFile) {
+  const explicit = String(explicitSpecFile || "").trim();
+  if (explicit) {
+    return path.resolve(targetPath, explicit);
+  }
+
+  const candidates = [path.join(targetPath, "SPEC.md"), path.join(targetPath, "docs", "spec.md")];
+  const found = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!found) {
+    throw new Error("No spec file found. Provide --spec-file or generate SPEC.md first.");
+  }
+  return found;
+}
+
+async function buildPromptOutput({
+  targetPath,
+  specFile,
+  agent,
+  outputFile,
+  outputDir = "",
+  refresh = false,
+}) {
+  const ingestResolution = await resolveCodebaseIngest({
+    rootPath: targetPath,
+    outputDir,
+    refresh,
+  });
+  const resolvedSpecPath = resolveSpecPath(targetPath, specFile);
+  const specMarkdown = await fsp.readFile(resolvedSpecPath, "utf-8");
+  const resolvedAgent = resolvePromptTarget(agent);
+  const promptMarkdown = generateExecutionPrompt({
+    specMarkdown,
+    target: resolvedAgent,
+    projectPath: targetPath,
+  });
+
+  const outputName = String(outputFile || "").trim() || defaultPromptFileName(resolvedAgent);
+  const outputPath = path.resolve(targetPath, outputName);
+
+  return {
+    agent: resolvedAgent,
+    specPath: resolvedSpecPath,
+    promptMarkdown,
+    outputPath,
+    ingestRefresh: {
+      outputPath: ingestResolution.outputPath,
+      refreshed: ingestResolution.refreshed,
+      stale: ingestResolution.stale,
+      reasons: ingestResolution.reasons,
+      refreshedBecause: ingestResolution.refreshedBecause,
+      lastCommitAt: ingestResolution.lastCommitAt,
+      contentHash: ingestResolution.fingerprint?.contentHash || "",
+    },
+  };
+}
+
+function resolvePromptArtifactPath({ targetPath, promptFile, agent }) {
+  const explicit = String(promptFile || "").trim();
+  if (explicit) {
+    return path.resolve(targetPath, explicit);
+  }
+
+  const resolvedAgent = resolvePromptTarget(agent);
+  const defaultPath = path.resolve(targetPath, defaultPromptFileName(resolvedAgent));
+  if (!fs.existsSync(defaultPath)) {
+    throw new Error(
+      `No prompt artifact found at ${defaultPath}. Generate one with 'prompt generate' or pass --file.`
+    );
+  }
+  return defaultPath;
+}
+
+export function registerPromptCommand(program) {
+  const prompt = program
+    .command("prompt")
+    .description("Generate agent execution prompts from SPEC content");
+
+  prompt
+    .command("generate")
+    .description("Generate prompt markdown file from spec")
+    .option("--path <path>", "Target workspace path", ".")
+    .option("--spec-file <path>", "Spec file path relative to --path")
+    .option("--agent <target>", `Prompt target (${SUPPORTED_PROMPT_TARGETS.join("|")})`, "generic")
+    .option("--output-file <path>", "Output prompt file path relative to --path")
+    .option("--output-dir <path>", "Optional output dir override for ingest cache")
+    .option("--refresh", "Refresh CODEBASE_INGEST before generating prompt")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await buildPromptOutput({
+        targetPath,
+        specFile: options.specFile,
+        agent: options.agent,
+        outputFile: options.outputFile,
+        outputDir: options.outputDir,
+        refresh: Boolean(options.refresh),
+      });
+
+      await fsp.mkdir(path.dirname(result.outputPath), { recursive: true });
+      await fsp.writeFile(result.outputPath, `${result.promptMarkdown.trimEnd()}\n`, "utf-8");
+
+      if (shouldEmitJson(options, command)) {
+        console.log(
+          JSON.stringify(
+            {
+              command: "prompt generate",
+              agent: result.agent,
+              specPath: result.specPath,
+              outputPath: result.outputPath,
+              ingestRefresh: result.ingestRefresh,
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      console.log(pc.bold("Prompt generated"));
+      console.log(pc.gray(`Agent: ${result.agent}`));
+      console.log(pc.gray(`Spec: ${result.specPath}`));
+      console.log(pc.gray(`Output: ${result.outputPath}`));
+      if (result.ingestRefresh?.stale || result.ingestRefresh?.refreshed) {
+        const color =
+          result.ingestRefresh?.stale && !result.ingestRefresh?.refreshed ? pc.yellow : pc.gray;
+        console.log(color(formatIngestResolutionNotice(result.ingestRefresh)));
+      }
+    });
+
+  prompt
+    .command("preview")
+    .description("Render generated prompt in terminal without writing file")
+    .option("--path <path>", "Target workspace path", ".")
+    .option("--spec-file <path>", "Spec file path relative to --path")
+    .option("--agent <target>", `Prompt target (${SUPPORTED_PROMPT_TARGETS.join("|")})`, "generic")
+    .option("--max-lines <n>", "Maximum lines to print (0 = unlimited)", "0")
+    .option("--output-dir <path>", "Optional output dir override for ingest cache")
+    .option("--refresh", "Refresh CODEBASE_INGEST before preview")
+    .option("--plain", "Disable terminal markdown styling")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await buildPromptOutput({
+        targetPath,
+        specFile: options.specFile,
+        agent: options.agent,
+        outputDir: options.outputDir,
+        refresh: Boolean(options.refresh),
+      });
+
+      const maxLines = Number.parseInt(String(options.maxLines || "0"), 10);
+      const lines = result.promptMarkdown.split(/\r?\n/);
+      const outputLines = Number.isFinite(maxLines) && maxLines > 0 ? lines.slice(0, maxLines) : lines;
+
+      if (shouldEmitJson(options, command)) {
+        console.log(
+          JSON.stringify(
+            {
+              command: "prompt preview",
+              agent: result.agent,
+              specPath: result.specPath,
+              lineCount: outputLines.length,
+              preview: outputLines.join("\n"),
+              ingestRefresh: result.ingestRefresh,
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      if (result.ingestRefresh?.stale || result.ingestRefresh?.refreshed) {
+        const color =
+          result.ingestRefresh?.stale && !result.ingestRefresh?.refreshed ? pc.yellow : pc.gray;
+        console.log(color(formatIngestResolutionNotice(result.ingestRefresh)));
+      }
+      console.log(renderTerminalMarkdown(outputLines.join("\n"), { plain: Boolean(options.plain) }));
+    });
+
+  prompt
+    .command("show")
+    .description("Render an existing prompt artifact in terminal markdown")
+    .option("--path <path>", "Target workspace path", ".")
+    .option("--file <path>", "Prompt file path relative to --path")
+    .option("--agent <target>", `Prompt target (${SUPPORTED_PROMPT_TARGETS.join("|")})`, "generic")
+    .option("--plain", "Disable terminal markdown styling")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const promptPath = resolvePromptArtifactPath({
+        targetPath,
+        promptFile: options.file,
+        agent: options.agent,
+      });
+      const markdown = await fsp.readFile(promptPath, "utf-8");
+
+      if (shouldEmitJson(options, command)) {
+        console.log(
+          JSON.stringify(
+            {
+              command: "prompt show",
+              promptPath,
+              lineCount: markdown.split(/\r?\n/).length,
+              preview: markdown,
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      console.log(renderTerminalMarkdown(markdown, { plain: Boolean(options.plain) }));
+    });
+}