sdtk-kit 0.3.9 → 1.0.1

package/assets/toolkit/toolkit/templates/handoffs/PM_TO_BA.md

@@ -1,26 +0,0 @@
-# PM to BA Handoff
-
-## Required Inputs
-- `docs/product/PROJECT_INITIATION_[FEATURE_KEY].md`
-- source requirement notes or attachments
-- current `SHARED_PLANNING.md`
-
-## Required Outputs
-- `docs/specs/BA_SPEC_[FEATURE_KEY].md`
-- updated `SHARED_PLANNING.md`
-- updated `QUALITY_CHECKLIST.md`
-
-## Mandatory Checks
-- `REQ-xx` scope is explicit and testable.
-- in-scope and out-of-scope are visible.
-- unresolved ambiguities are logged as `OQ-xx`, not hidden.
-
-## Forbidden Shortcuts
-- Do not skip glossary, BR, UC, AC, or traceability expectations.
-- Do not invent missing stakeholder decisions without logging them.
-
-## Handoff Message Shape
-- Feature: `[FEATURE_KEY]`
-- PM scope summary: 3 to 7 bullets
-- Known open questions: `OQ-xx` list or `None`
-- Expected BA focus: rules, use cases, acceptance criteria, NFRs

package/assets/toolkit/toolkit/templates/handoffs/QA_RELEASE_DECISION.md

@@ -1,21 +0,0 @@
-# QA Release Decision
-
-## Required Inputs
-- `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
-- Stage 1 and Stage 2 DEV review PASS evidence
-- fresh proving checks or benchmark-mode evidence
-- open defect list with severity
-
-## Required Outputs
-- `APPROVED` or `REJECTED`
-- explicit evidence summary
-- unresolved risks and assumptions list
-
-## Mandatory Checks
-- verdict is backed by fresh command evidence or benchmark policy
-- specification quotes are used for requirement-based validation
-- defects and known gaps are visible in the decision
-
-## Forbidden Shortcuts
-- Do not issue `APPROVED` based on planned checks.
-- Do not hide environment limitations; state when runtime verification was not possible.

package/bin/sdtk.js

@@ -1,15 +0,0 @@
-#!/usr/bin/env node
-
-"use strict";
-
-const { run } = require("../src/index");
-
-run(process.argv.slice(2))
-  .then((exitCode) => {
-    process.exitCode = Number.isInteger(exitCode) ? exitCode : 0;
-  })
-  .catch((error) => {
-    console.error(`sdtk: ${error.message}`);
-    process.exitCode =
-      typeof error.exitCode === "number" ? error.exitCode : 4;
-  });

package/src/commands/auth.js

@@ -1,85 +0,0 @@
-"use strict";
-
-const { clearAuthState, readAuthState, writeAuthState } = require("../lib/state");
-const { parseFlags } = require("../lib/args");
-const { checkRepoAccess } = require("../lib/github-access");
-const { ValidationError } = require("../lib/errors");
-
-const FLAG_DEFS = {
-  token: { type: "string" },
-  status: { type: "boolean" },
-  logout: { type: "boolean" },
-  verify: { type: "boolean" },
-};
-
-/**
- * Redact a token for safe display (show first 4 chars only).
- */
-function redactToken(token) {
-  if (!token || token.length < 8) return "****";
-  return token.slice(0, 4) + "****";
-}
-
-async function cmdAuth(args) {
-  const { flags } = parseFlags(args, FLAG_DEFS);
-
-  if (flags.status) {
-    const state = readAuthState();
-    if (!state.authenticated) {
-      console.log("Auth status: not authenticated");
-      console.log('Run "sdtk auth --token <value>" to authenticate.');
-      return 1;
-    }
-    console.log("Auth status: authenticated");
-    console.log(`Token: ${redactToken(state.token)}`);
-    return 0;
-  }
-
-  if (flags.logout) {
-    clearAuthState();
-    console.log("Auth state cleared.");
-    return 0;
-  }
-
-  // Process --token first, then optionally --verify in the same invocation.
-  // This supports: sdtk auth --token <value> --verify
-  if (flags.token) {
-    const { path: authFile, hardened } = writeAuthState(flags.token);
-    if (hardened) {
-      console.log("Token stored securely.");
-    } else {
-      console.log("Token stored (file permission hardening was not applied).");
-    }
-    console.log(`Auth file: ${authFile}`);
-
-    if (flags.verify) {
-      console.log("");
-      console.log("Verifying repository access...");
-      const result = await checkRepoAccess(flags.token);
-      console.log(result.message);
-      return result.hasAccess ? 0 : 1;
-    }
-
-    console.log('Run "sdtk auth --verify" to check repository access.');
-    return 0;
-  }
-
-  if (flags.verify) {
-    const state = readAuthState();
-    if (!state.authenticated) {
-      console.log("Not authenticated. Store a token first with --token.");
-      return 1;
-    }
-    const result = await checkRepoAccess(state.token);
-    console.log(result.message);
-    return result.hasAccess ? 0 : 1;
-  }
-
-  throw new ValidationError(
-    "Usage: sdtk auth --token <value> [--verify] | --status | --logout"
-  );
-}
-
-module.exports = {
-  cmdAuth,
-};

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,
-};