sdtk-kit 0.3.0

package/src/commands/generate.js

@@ -0,0 +1,177 @@
+"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

@@ -0,0 +1,69 @@
+"use strict";
+
+function cmdHelp() {
+  const text = [
+    "SDTK CLI -- deterministic documentation toolkit",
+    "",
+    "Usage:",
+    "  sdtk <command> [options]",
+    "",
+    "Commands:",
+    "  init      Initialize SDTK workspace (runtime adapter + config)",
+    "  auth      Manage GitHub authentication and entitlement",
+    "  generate  Generate feature documentation from templates",
+    "",
+    "Init options:",
+    "  --runtime <codex|claude>   Runtime adapter (default: codex)",
+    "  --project-path <path>      Target project directory (default: cwd)",
+    "  --force                    Overwrite existing files",
+    "  --skip-skills              Skip Codex skill installation",
+    "  --verbose                  Show detailed PowerShell script output",
+    "",
+    "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",
+    "",
+    "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",
+    "",
+    "  # 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

@@ -0,0 +1,73 @@
+"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 FLAG_DEFS = {
+  runtime: { type: "string" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+  "skip-skills": { 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 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,
+  };
+  if (flags.force) params.Force = true;
+  if (flags["skip-skills"]) params.SkipSkills = true;
+  if (!flags.verbose) params.Quiet = true;
+
+  console.log(`Initializing SDTK workspace...`);
+  console.log(`  Runtime: ${runtime}`);
+  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/index.js

@@ -0,0 +1,56 @@
+"use strict";
+
+const { cmdHelp } = require("./commands/help");
+const { cmdInit } = require("./commands/init");
+const { cmdAuth } = require("./commands/auth");
+const { cmdGenerate } = require("./commands/generate");
+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"]);
+
+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);
+  }
+}
+
+module.exports = {
+  run,
+};

package/src/lib/args.js

@@ -0,0 +1,116 @@
+"use strict";
+
+const { ValidationError } = require("./errors");
+
+/**
+ * Parse argv into a structured flags object.
+ * Supports: --flag value, --flag=value, --bool-flag (no value).
+ *
+ * @param {string[]} argv - Raw arguments (after command is stripped).
+ * @param {Object<string, {type: 'string'|'boolean', required?: boolean, alias?: string}>} defs - Flag definitions.
+ * @returns {{ flags: Object, positional: string[] }}
+ */
+function parseFlags(argv, defs) {
+  const flags = {};
+  const positional = [];
+  const aliasMap = {};
+
+  for (const [name, def] of Object.entries(defs)) {
+    if (def.alias) aliasMap[def.alias] = name;
+    if (def.type === "boolean") flags[name] = false;
+    else flags[name] = undefined;
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (!arg.startsWith("-")) {
+      positional.push(arg);
+      i++;
+      continue;
+    }
+
+    let key;
+    let inlineValue;
+
+    if (arg.includes("=")) {
+      const eqIdx = arg.indexOf("=");
+      key = arg.slice(0, eqIdx);
+      inlineValue = arg.slice(eqIdx + 1);
+    } else {
+      key = arg;
+    }
+
+    // Normalize: strip leading dashes, resolve alias
+    const stripped = key.replace(/^-{1,2}/, "");
+    const resolved = aliasMap[stripped] || stripped;
+
+    if (!(resolved in defs)) {
+      throw new ValidationError(`Unknown flag: ${key}`);
+    }
+
+    const def = defs[resolved];
+
+    if (def.type === "boolean") {
+      flags[resolved] = true;
+      i++;
+    } else {
+      // string type
+      let value = inlineValue;
+      if (value === undefined) {
+        i++;
+        if (i >= argv.length) {
+          throw new ValidationError(`Flag ${key} requires a value.`);
+        }
+        value = argv[i];
+      }
+      flags[resolved] = value;
+      i++;
+    }
+  }
+
+  return { flags, positional };
+}
+
+/**
+ * Require a flag to be present (non-undefined, non-empty for strings).
+ */
+function requireFlag(flags, name, label) {
+  const val = flags[name];
+  if (val === undefined || val === null || val === "") {
+    throw new ValidationError(`Missing required flag: --${label || name}`);
+  }
+  return val;
+}
+
+/**
+ * Validate a value is one of the allowed choices.
+ */
+function validateChoice(value, choices, label) {
+  if (!choices.includes(value)) {
+    throw new ValidationError(
+      `Invalid value for --${label}: "${value}". Must be one of: ${choices.join(", ")}`
+    );
+  }
+  return value;
+}
+
+/**
+ * Validate a value matches a regex pattern.
+ */
+function validatePattern(value, regex, label, hint) {
+  if (!regex.test(value)) {
+    throw new ValidationError(
+      `Invalid value for --${label}: "${value}". ${hint || `Must match ${regex}`}`
+    );
+  }
+  return value;
+}
+
+module.exports = {
+  parseFlags,
+  requireFlag,
+  validateChoice,
+  validatePattern,
+};

package/src/lib/errors.js

@@ -0,0 +1,41 @@
+"use strict";
+
+class CliError extends Error {
+  constructor(message, exitCode = 4) {
+    super(message);
+    this.name = this.constructor.name;
+    this.exitCode = exitCode;
+  }
+}
+
+class ValidationError extends CliError {
+  constructor(message) {
+    super(message, 1);
+  }
+}
+
+class DependencyError extends CliError {
+  constructor(message) {
+    super(message, 2);
+  }
+}
+
+class IntegrityError extends CliError {
+  constructor(message) {
+    super(message, 3);
+  }
+}
+
+class InternalError extends CliError {
+  constructor(message) {
+    super(message, 4);
+  }
+}
+
+module.exports = {
+  CliError,
+  ValidationError,
+  DependencyError,
+  IntegrityError,
+  InternalError,
+};

package/src/lib/github-access.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const { ValidationError } = require("./errors");
+
+// Entitlement repo: configurable via env var, falls back to default.
+// Set SDTK_ENTITLEMENT_REPO=owner/repo to override.
+const DEFAULT_REPO = "DucTN/sdtk-private";
+
+function getEntitlementRepo() {
+  return process.env.SDTK_ENTITLEMENT_REPO || DEFAULT_REPO;
+}
+
+/**
+ * Check if a GitHub token has access to the private distribution repo.
+ *
+ * @param {string} token - GitHub PAT.
+ * @param {string} [repo] - Repo in "owner/name" format. Defaults to SDTK_ENTITLEMENT_REPO env or built-in default.
+ * @returns {Promise<{hasAccess: boolean, message: string}>}
+ */
+async function checkRepoAccess(token, repo) {
+  const targetRepo = repo || getEntitlementRepo();
+  const url = `https://api.github.com/repos/${targetRepo}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "sdtk-cli",
+      },
+    });
+
+    if (response.status === 200) {
+      return {
+        hasAccess: true,
+        message: `Access verified for ${targetRepo}.`,
+      };
+    }
+
+    if (response.status === 404 || response.status === 403) {
+      return {
+        hasAccess: false,
+        message: `No access to ${targetRepo}. Check your token permissions.`,
+      };
+    }
+
+    if (response.status === 401) {
+      return {
+        hasAccess: false,
+        message: "Token is invalid or expired.",
+      };
+    }
+
+    return {
+      hasAccess: false,
+      message: `Unexpected response (HTTP ${response.status}) from GitHub API.`,
+    };
+  } catch (err) {
+    throw new ValidationError(
+      `Failed to reach GitHub API: ${err.message}\nCheck your network connection.`
+    );
+  }
+}
+
+module.exports = {
+  checkRepoAccess,
+  getEntitlementRepo,
+};

package/src/lib/powershell.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const { execFile } = require("child_process");
+const { DependencyError } = require("./errors");
+
+/**
+ * Find available PowerShell executable.
+ * Prefers pwsh (PowerShell Core) over powershell.exe (Windows PowerShell).
+ * @returns {string} PowerShell executable name.
+ */
+function findPowerShell() {
+  // On Windows, powershell.exe is always available
+  // pwsh (PowerShell Core) is preferred if available
+  if (process.platform === "win32") {
+    return "powershell.exe";
+  }
+  // On non-Windows, pwsh must be installed
+  return "pwsh";
+}
+
+/**
+ * Execute a PowerShell script file with arguments.
+ *
+ * @param {string} scriptPath - Absolute path to the .ps1 file.
+ * @param {Object<string, string|boolean>} params - Parameters to pass.
+ *   String values become `-ParamName "value"`, boolean true becomes `-ParamName`.
+ * @param {Object} [options] - Optional settings.
+ * @param {boolean} [options.silent] - If true, suppress stdout output.
+ * @returns {Promise<{exitCode: number, stdout: string, stderr: string}>}
+ */
+function runScript(scriptPath, params = {}, options = {}) {
+  return new Promise((resolve, reject) => {
+    const psExe = findPowerShell();
+    const args = [
+      "-ExecutionPolicy",
+      "Bypass",
+      "-NoProfile",
+      "-NonInteractive",
+      "-File",
+      scriptPath,
+    ];
+
+    // Build parameters safely using execFile array args
+    for (const [key, value] of Object.entries(params)) {
+      if (value === true) {
+        args.push(`-${key}`);
+      } else if (value === false || value === undefined || value === null) {
+        // Skip false/undefined/null switches
+      } else {
+        args.push(`-${key}`);
+        args.push(String(value));
+      }
+    }
+
+    execFile(psExe, args, { maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error && error.code === "ENOENT") {
+        reject(
+          new DependencyError(
+            `PowerShell not found. Ensure PowerShell is installed and available in PATH.\n` +
+              `Tried: ${psExe}`
+          )
+        );
+        return;
+      }
+
+      const exitCode = error ? error.code || 1 : 0;
+      const result = {
+        exitCode: typeof exitCode === "number" ? exitCode : 1,
+        stdout: stdout || "",
+        stderr: stderr || "",
+      };
+
+      if (!options.silent && result.stdout) {
+        process.stdout.write(result.stdout);
+      }
+
+      resolve(result);
+    });
+  });
+}
+
+module.exports = {
+  runScript,
+  findPowerShell,
+};