sdtk-kit 0.3.8 → 1.0.0

package/src/commands/generate.js

@@ -1,177 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const { parseFlags, requireFlag, validatePattern } = require("../lib/args");
-const { verify, resolvePayloadFile } = require("../lib/toolkit-payload");
-const { runScript } = require("../lib/powershell");
-const { ValidationError } = require("../lib/errors");
-
-/**
- * Expected 17 output files from generate.
- * Placeholders: {KEY} = UPPER_SNAKE_CASE, {PASCAL} = PascalCase, {SNAKE} = lower_snake_case
- */
-const EXPECTED_OUTPUT_FILES = [
-  "SHARED_PLANNING.md",
-  "QUALITY_CHECKLIST.md",
-  "docs/product/PROJECT_INITIATION_{KEY}.md",
-  "docs/specs/BA_SPEC_{KEY}.md",
-  "docs/specs/{KEY}_FLOW_ACTION_SPEC.md",
-  "docs/product/PRD_{KEY}.md",
-  "docs/product/BACKLOG_{KEY}.md",
-  "docs/architecture/ARCH_DESIGN_{KEY}.md",
-  "docs/database/DATABASE_SPEC_{KEY}.md",
-  "docs/api/{PASCAL}_API.yaml",
-  "docs/api/{KEY}_ENDPOINTS.md",
-  "docs/api/{KEY}_API_DESIGN_DETAIL.md",
-  "docs/api/{SNAKE}_api_flow_list.txt",
-  "docs/design/DESIGN_LAYOUT_{KEY}.md",
-  "docs/dev/FEATURE_IMPL_PLAN_{KEY}.md",
-  "docs/qa/{KEY}_TEST_CASE.md",
-  "docs/qa/QA_RELEASE_REPORT_{KEY}.md",
-];
-
-/**
- * Convert text to PascalCase.
- * Mirrors init-feature.ps1 ConvertTo-PascalCase: split on non-alphanumeric,
- * capitalize first letter of each part, preserve rest of casing per part.
- * e.g. "Order Management" -> "OrderManagement", "USER_PROFILE" -> "UserProfile"
- */
-function toPascalCase(text) {
-  const parts = text.split(/[^A-Za-z0-9]+/).filter((p) => p.length > 0);
-  return parts
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-    .join("");
-}
-
-/**
- * Derive PascalCase matching init-feature.ps1 logic:
- * prefer featureName, fallback to featureKey.
- */
-function derivePascalCase(featureName, featureKey) {
-  const fromName = toPascalCase(featureName);
-  return fromName || toPascalCase(featureKey);
-}
-
-/**
- * Convert UPPER_SNAKE_CASE to lower_snake_case.
- */
-function toSnakeCase(upperSnake) {
-  return upperSnake.toLowerCase();
-}
-
-/**
- * Expand placeholders and return list of expected file paths relative to project root.
- */
-function expandExpectedFiles(featureKey, featureName) {
-  const pascal = derivePascalCase(featureName, featureKey);
-  const snake = toSnakeCase(featureKey);
-  return EXPECTED_OUTPUT_FILES.map((tmpl) =>
-    tmpl.replace(/\{KEY\}/g, featureKey).replace(/\{PASCAL\}/g, pascal).replace(/\{SNAKE\}/g, snake)
-  );
-}
-
-/**
- * Verify all 17 expected output files exist under projectPath.
- * Returns list of missing files (empty if all present).
- */
-function verifyOutputContract(projectPath, featureKey, featureName) {
-  const expected = expandExpectedFiles(featureKey, featureName);
-  const missing = [];
-  for (const rel of expected) {
-    const full = path.join(projectPath, rel);
-    if (!fs.existsSync(full)) {
-      missing.push(rel);
-    }
-  }
-  return missing;
-}
-
-const FLAG_DEFS = {
-  "feature-key": { type: "string" },
-  "feature-name": { type: "string" },
-  "project-path": { type: "string" },
-  force: { type: "boolean" },
-  "validate-only": { type: "boolean" },
-  verbose: { type: "boolean" },
-};
-
-const FEATURE_KEY_REGEX = /^[A-Z][A-Z0-9_]*$/;
-
-async function cmdGenerate(args) {
-  const { flags } = parseFlags(args, FLAG_DEFS);
-
-  // Validate required flags
-  const featureKey = requireFlag(flags, "feature-key", "feature-key");
-  const featureName = requireFlag(flags, "feature-name", "feature-name");
-
-  // Validate feature key format
-  validatePattern(
-    featureKey,
-    FEATURE_KEY_REGEX,
-    "feature-key",
-    "Must be UPPER_SNAKE_CASE (e.g., USER_PROFILE, ORDER_MANAGEMENT)."
-  );
-
-  // Resolve project path
-  const projectPath = flags["project-path"]
-    ? path.resolve(flags["project-path"])
-    : process.cwd();
-
-  // Verify payload integrity before proceeding
-  verify();
-
-  // Resolve bundled init-feature.ps1
-  const generateScript = resolvePayloadFile(
-    "toolkit/scripts/init-feature.ps1"
-  );
-
-  // Build PowerShell parameters
-  const params = {
-    FeatureKey: featureKey,
-    FeatureName: featureName,
-    ProjectPath: projectPath,
-  };
-  if (flags.force) params.Force = true;
-  if (flags["validate-only"]) params.ValidateOnly = true;
-
-  console.log(`Generating documentation for feature: ${featureKey}`);
-  console.log(`  Feature name: ${featureName}`);
-  console.log(`  Project path: ${projectPath}`);
-  if (flags["validate-only"]) {
-    console.log("  Mode: validate-only (no files will be written)");
-  }
-  console.log("");
-
-  const result = await runScript(generateScript, params, { silent: !flags.verbose });
-
-  if (result.exitCode !== 0) {
-    if (result.stderr) {
-      console.error(result.stderr);
-    }
-    throw new ValidationError(
-      `Generation failed (exit code ${result.exitCode}).`
-    );
-  }
-
-  // Enforce 17-file output contract (skip for validate-only mode)
-  if (!flags["validate-only"]) {
-    const missing = verifyOutputContract(projectPath, featureKey, featureName);
-    if (missing.length > 0) {
-      console.error("\nOutput contract violation -- missing files:");
-      for (const f of missing) {
-        console.error(`  - ${f}`);
-      }
-      throw new ValidationError(
-        `Expected 17 output files but ${missing.length} missing. See list above.`
-      );
-    }
-    console.log("\nAll 17 expected output files verified.");
-  }
-
-  return 0;
-}
-
-module.exports = {
-  cmdGenerate,
-};

package/src/commands/help.js

@@ -1,101 +0,0 @@
-"use strict";
-
-function cmdHelp() {
-  const text = [
-    "SDTK CLI -- deterministic documentation toolkit",
-    "",
-    "Usage:",
-    "  sdtk <command> [options]",
-    "",
-    "Commands:",
-    "  init      Initialize SDTK workspace (runtime adapter + config)",
-    "  runtime   Manage runtime asset installation (install, uninstall, status)",
-    "  auth      Manage GitHub authentication and entitlement",
-    "  generate  Scaffold feature documentation from templates (17 files)",
-    "",
-    "Init options:",
-    "  --runtime <codex|claude>       Runtime adapter (default: codex)",
-    "  --runtime-scope <project|user> Install scope (default: project for claude, user for codex)",
-    "  --project-path <path>          Target project directory (default: cwd)",
-    "  --force                        Overwrite existing files",
-    "  --skip-runtime-assets          Skip runtime asset installation",
-    "  --skip-skills                  (deprecated, use --skip-runtime-assets)",
-    "  --verbose                      Show detailed PowerShell script output",
-    "",
-    "Runtime subcommands:",
-    "  sdtk runtime install   --runtime <codex|claude> [--scope <project|user>]",
-    "  sdtk runtime uninstall --runtime <codex|claude> [--scope <project|user>] [--all]",
-    "  sdtk runtime status    --runtime <codex|claude>",
-    "",
-    "Runtime options:",
-    "  --runtime <codex|claude>   Target runtime (required)",
-    "  --scope <project|user>     Install scope (default: project for claude, user for codex)",
-    "  --project-path <path>      Target project directory (default: cwd)",
-    "  --force                    Overwrite existing skills",
-    "  --all                      Uninstall all managed skills",
-    "  --verbose                  Show detailed script output",
-    "",
-    "Scope behavior:",
-    "  project  Skills are installed inside the repo (Claude only: .claude/skills/)",
-    "  user     Skills are installed in the runtime home (~/.claude/skills/ or ~/.codex/skills/)",
-    "  Note: Codex supports user scope only. Project scope is not available for Codex.",
-    "",
-    "Auth options:",
-    "  --token <value>            Store GitHub PAT",
-    "  --verify                   Check private repo access",
-    "  --status                   Show authentication status",
-    "  --logout                   Clear stored credentials",
-    "",
-    "Generate options:",
-    "  --feature-key <KEY>        Feature identifier (UPPER_SNAKE_CASE, required)",
-    "  --feature-name \"<text>\"    Human-readable feature name (required)",
-    "  --project-path <path>      Target project directory (default: cwd)",
-    "  --force                    Overwrite existing files",
-    "  --validate-only            Validate templates without writing files",
-    "  --verbose                  Show detailed PowerShell script output",
-    "",
-    "Generate behavior:",
-    "  The generate command creates 17 scaffold files with TBD placeholders.",
-    "  Scaffolds define document structure for each SDLC phase.",
-    "  Content is filled in by agents or manually (PM -> BA -> ARCH -> DEV -> QA).",
-    "  Output is written to docs/ subdirectories under the project path.",
-    "",
-    "Global options:",
-    "  -h, --help                 Show this help",
-    "  -v, --version              Show version",
-    "",
-    "Exit codes:",
-    "  0  Success",
-    "  1  Validation or user error",
-    "  2  Dependency error (e.g., PowerShell not found)",
-    "  3  Integrity error (payload hash mismatch)",
-    "  4  Unexpected internal error",
-    "",
-    "Environment variables:",
-    "  SDTK_ENTITLEMENT_REPO   Override default entitlement repo (owner/repo format)",
-    "",
-    "Examples:",
-    "  sdtk init --runtime codex",
-    "  sdtk init --runtime claude --project-path ./my-project",
-    "  sdtk auth --token ghp_xxxxxxxxxxxx",
-    "  sdtk auth --verify",
-    '  sdtk generate --feature-key USER_PROFILE --feature-name "User Profile"',
-    "  sdtk generate --feature-key ORDER_MGMT --feature-name \"Order Management\" --validate-only",
-    "  sdtk init --runtime claude --runtime-scope user",
-    "  sdtk runtime install --runtime claude --scope project",
-    "  sdtk runtime install --runtime codex --scope user",
-    "  sdtk runtime status --runtime claude",
-    "  sdtk runtime uninstall --runtime claude --scope project --all",
-    "",
-    "  # Override entitlement repo (bash/zsh):",
-    "  export SDTK_ENTITLEMENT_REPO=owner/repo",
-    "  # Override entitlement repo (PowerShell):",
-    '  $env:SDTK_ENTITLEMENT_REPO="owner/repo"',
-  ];
-  console.log(text.join("\n"));
-  return 0;
-}
-
-module.exports = {
-  cmdHelp,
-};

package/src/commands/init.js

@@ -1,97 +0,0 @@
-"use strict";
-
-const path = require("path");
-const { parseFlags, validateChoice } = require("../lib/args");
-const { verify, resolvePayloadFile } = require("../lib/toolkit-payload");
-const { runScript } = require("../lib/powershell");
-const { ValidationError } = require("../lib/errors");
-const { VALID_SCOPES, defaultScope, isProjectScopeSupported } = require("../lib/scope");
-
-const FLAG_DEFS = {
-  runtime: { type: "string" },
-  "project-path": { type: "string" },
-  "runtime-scope": { type: "string" },
-  force: { type: "boolean" },
-  "skip-skills": { type: "boolean" },
-  "skip-runtime-assets": { type: "boolean" },
-  verbose: { type: "boolean" },
-};
-
-const VALID_RUNTIMES = ["codex", "claude"];
-
-async function cmdInit(args) {
-  const { flags } = parseFlags(args, FLAG_DEFS);
-
-  // Validate runtime
-  const runtime = flags.runtime || "codex";
-  validateChoice(runtime, VALID_RUNTIMES, "runtime");
-
-  // Resolve scope
-  const scope = flags["runtime-scope"] || defaultScope(runtime);
-  validateChoice(scope, VALID_SCOPES, "runtime-scope");
-
-  // Gate C0: Codex does not support project-local skills
-  if (scope === "project" && !isProjectScopeSupported(runtime)) {
-    throw new ValidationError(
-      "Codex does not support project-local skills. Use --runtime-scope user instead."
-    );
-  }
-
-  // Handle deprecated --skip-skills
-  const skipAssets = flags["skip-runtime-assets"] || flags["skip-skills"];
-  if (flags["skip-skills"] && !flags["skip-runtime-assets"]) {
-    console.warn(
-      "Warning: --skip-skills is deprecated. Use --skip-runtime-assets instead."
-    );
-  }
-
-  // Resolve project path
-  const projectPath = flags["project-path"]
-    ? path.resolve(flags["project-path"])
-    : process.cwd();
-
-  // Verify payload integrity before proceeding
-  verify();
-
-  // Resolve bundled install.ps1
-  const installScript = resolvePayloadFile("toolkit/install.ps1");
-
-  // Build PowerShell parameters
-  const params = {
-    ProjectPath: projectPath,
-    Runtime: runtime,
-    Scope: scope,
-  };
-  if (flags.force) params.Force = true;
-  if (skipAssets) params.SkipRuntimeAssets = true;
-  if (!flags.verbose) params.Quiet = true;
-
-  console.log(`Initializing SDTK workspace...`);
-  console.log(`  Runtime: ${runtime}`);
-  console.log(`  Scope:   ${scope}`);
-  console.log(`  Project: ${projectPath}`);
-  console.log("");
-
-  const result = await runScript(installScript, params, { silent: !flags.verbose });
-
-  if (result.exitCode !== 0) {
-    if (result.stderr) {
-      console.error(result.stderr);
-    }
-    throw new ValidationError(
-      `Initialization failed (exit code ${result.exitCode}).`
-    );
-  }
-
-  console.log("");
-  console.log("SDTK workspace initialized successfully.");
-  console.log("");
-  console.log("Next steps:");
-  console.log("  1. Review and customize sdtk.config.json for your project stack.");
-  console.log('  2. Run "sdtk generate --feature-key <KEY> --feature-name <name>" to scaffold docs.');
-  return 0;
-}
-
-module.exports = {
-  cmdInit,
-};

package/src/commands/runtime.js

@@ -1,217 +0,0 @@
-"use strict";
-
-const path = require("path");
-const fs = require("fs");
-const { parseFlags, requireFlag, validateChoice } = require("../lib/args");
-const { verify, resolvePayloadFile } = require("../lib/toolkit-payload");
-const { runScript } = require("../lib/powershell");
-const { ValidationError } = require("../lib/errors");
-const {
-  VALID_SCOPES,
-  defaultScope,
-  isProjectScopeSupported,
-  resolveSkillsDir,
-  managedSkillNames,
-} = require("../lib/scope");
-
-const FLAG_DEFS = {
-  runtime: { type: "string" },
-  scope: { type: "string" },
-  "project-path": { type: "string" },
-  force: { type: "boolean" },
-  all: { type: "boolean" },
-  verbose: { type: "boolean" },
-};
-
-const VALID_RUNTIMES = ["codex", "claude"];
-const SUBCOMMANDS = ["install", "uninstall", "status"];
-
-function validateScopeForRuntime(runtime, scope) {
-  if (scope === "project" && !isProjectScopeSupported(runtime)) {
-    throw new ValidationError(
-      `Codex does not support project-local skills. Use --scope user instead.`
-    );
-  }
-}
-
-async function cmdRuntimeInstall(flags) {
-  const runtime = requireFlag(flags, "runtime", "runtime");
-  validateChoice(runtime, VALID_RUNTIMES, "runtime");
-
-  const scope = flags.scope || defaultScope(runtime);
-  validateChoice(scope, VALID_SCOPES, "scope");
-  validateScopeForRuntime(runtime, scope);
-
-  const projectPath = flags["project-path"]
-    ? path.resolve(flags["project-path"])
-    : process.cwd();
-
-  verify();
-
-  const scriptName =
-    runtime === "claude"
-      ? "toolkit/scripts/install-claude-skills.ps1"
-      : "toolkit/scripts/install-codex-skills.ps1";
-  const script = resolvePayloadFile(scriptName);
-
-  const params = { Scope: scope };
-  if (runtime === "claude") {
-    params.ProjectPath = projectPath;
-  }
-  if (flags.force) params.Force = true;
-
-  console.log(`Installing ${runtime} runtime assets...`);
-  console.log(`  Runtime: ${runtime}`);
-  console.log(`  Scope:   ${scope}`);
-  if (scope === "project") {
-    console.log(`  Project: ${projectPath}`);
-  }
-  console.log("");
-
-  const result = await runScript(script, params, {
-    silent: !flags.verbose,
-  });
-
-  if (result.exitCode !== 0) {
-    if (result.stderr) console.error(result.stderr);
-    throw new ValidationError(
-      `Runtime install failed (exit code ${result.exitCode}).`
-    );
-  }
-
-  console.log("");
-  console.log(`${runtime} runtime assets installed successfully.`);
-  return 0;
-}
-
-async function cmdRuntimeUninstall(flags) {
-  const runtime = requireFlag(flags, "runtime", "runtime");
-  validateChoice(runtime, VALID_RUNTIMES, "runtime");
-
-  const scope = flags.scope || defaultScope(runtime);
-  validateChoice(scope, VALID_SCOPES, "scope");
-  validateScopeForRuntime(runtime, scope);
-
-  const projectPath = flags["project-path"]
-    ? path.resolve(flags["project-path"])
-    : process.cwd();
-
-  verify();
-
-  const scriptName =
-    runtime === "claude"
-      ? "toolkit/scripts/uninstall-claude-skills.ps1"
-      : "toolkit/scripts/uninstall-codex-skills.ps1";
-  const script = resolvePayloadFile(scriptName);
-
-  const params = {};
-  if (runtime === "claude") {
-    params.Scope = scope;
-    params.ProjectPath = projectPath;
-  }
-  if (flags.all) params.All = true;
-
-  console.log(`Uninstalling ${runtime} runtime assets...`);
-  console.log(`  Runtime: ${runtime}`);
-  console.log(`  Scope:   ${scope}`);
-  console.log("");
-
-  const result = await runScript(script, params, {
-    silent: !flags.verbose,
-  });
-
-  if (result.exitCode !== 0) {
-    if (result.stderr) console.error(result.stderr);
-    throw new ValidationError(
-      `Runtime uninstall failed (exit code ${result.exitCode}).`
-    );
-  }
-
-  console.log("");
-  console.log(`${runtime} runtime assets uninstalled successfully.`);
-  return 0;
-}
-
-function cmdRuntimeStatus(flags) {
-  const runtime = requireFlag(flags, "runtime", "runtime");
-  validateChoice(runtime, VALID_RUNTIMES, "runtime");
-
-  const projectPath = flags["project-path"]
-    ? path.resolve(flags["project-path"])
-    : process.cwd();
-
-  console.log(`Runtime: ${runtime}`);
-  console.log("");
-
-  // Check both scopes
-  const scopes = runtime === "claude" ? ["project", "user"] : ["user"];
-
-  for (const scope of scopes) {
-    const skillsDir = resolveSkillsDir(runtime, scope, projectPath);
-    const exists = fs.existsSync(skillsDir);
-    let skillCount = 0;
-
-    const managed = managedSkillNames(runtime);
-    let installedNames = [];
-
-    if (exists) {
-      try {
-        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-        installedNames = entries
-          .filter((e) => e.isDirectory() && managed.includes(e.name))
-          .map((e) => e.name);
-        skillCount = installedNames.length;
-      } catch {
-        // Directory not readable
-      }
-    }
-
-    const allInstalled = skillCount === managed.length;
-
-    console.log(`  Scope: ${scope}`);
-    console.log(`    Path:   ${skillsDir}`);
-    const statusLabel = !exists
-      ? "not installed"
-      : allInstalled
-        ? `installed (${skillCount}/${managed.length} SDTK skills)`
-        : `partial (${skillCount}/${managed.length} SDTK skills)`;
-    console.log(`    Status: ${statusLabel}`);
-    if (exists && skillCount < managed.length) {
-      const missing = managed.filter((n) => !installedNames.includes(n));
-      console.log(`    Missing: ${missing.join(", ")}`);
-    }
-    console.log("");
-  }
-
-  return 0;
-}
-
-async function cmdRuntime(args) {
-  const { flags, positional } = parseFlags(args, FLAG_DEFS);
-
-  const subcommand = positional[0];
-  if (!subcommand) {
-    throw new ValidationError(
-      `Missing subcommand. Usage: sdtk runtime <${SUBCOMMANDS.join("|")}> [options]`
-    );
-  }
-
-  if (!SUBCOMMANDS.includes(subcommand)) {
-    throw new ValidationError(
-      `Unknown subcommand: "${subcommand}". Must be one of: ${SUBCOMMANDS.join(", ")}`
-    );
-  }
-
-  switch (subcommand) {
-    case "install":
-      return cmdRuntimeInstall(flags);
-    case "uninstall":
-      return cmdRuntimeUninstall(flags);
-    case "status":
-      return cmdRuntimeStatus(flags);
-  }
-}
-
-module.exports = {
-  cmdRuntime,
-};

package/src/index.js

@@ -1,59 +0,0 @@
-"use strict";
-
-const { cmdHelp } = require("./commands/help");
-const { cmdInit } = require("./commands/init");
-const { cmdAuth } = require("./commands/auth");
-const { cmdGenerate } = require("./commands/generate");
-const { cmdRuntime } = require("./commands/runtime");
-const { ValidationError, CliError } = require("./lib/errors");
-
-function getVersion() {
-  const pkg = require("../package.json");
-  return pkg.version;
-}
-
-function parseCommand(argv) {
-  if (!argv || argv.length === 0) {
-    return { command: "help", args: [] };
-  }
-  const [first, ...rest] = argv;
-  if (first === "-h" || first === "--help") {
-    return { command: "help", args: [] };
-  }
-  if (first === "-v" || first === "--version") {
-    return { command: "version", args: [] };
-  }
-  return { command: first, args: rest };
-}
-
-const COMMANDS = new Set(["help", "version", "init", "auth", "generate", "runtime"]);
-
-async function run(argv) {
-  const { command, args } = parseCommand(argv);
-
-  if (!COMMANDS.has(command)) {
-    throw new ValidationError(
-      `Unknown command: "${command}". Run "sdtk --help" for available commands.`
-    );
-  }
-
-  switch (command) {
-    case "help":
-      return cmdHelp();
-    case "version":
-      console.log(`sdtk-kit ${getVersion()}`);
-      return 0;
-    case "init":
-      return cmdInit(args);
-    case "auth":
-      return cmdAuth(args);
-    case "generate":
-      return cmdGenerate(args);
-    case "runtime":
-      return cmdRuntime(args);
-  }
-}
-
-module.exports = {
-  run,
-};