showdar-skills 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.0]
+
+### Added
+
+- `showdar update-pack <path> --dry-run` read-only snapshot preview using the same canonical planning logic as execution; explicit public projection with deterministic ordering, descriptive change categories (`source-only`, `skill-content`, `workflow-definition`, `profile-definition`, `metadata`, `reference`, `ownership`, `installed-drift`), and `executable` status.
+- Canonical internal pack update planning (`src/pack-plan.js`): `planPackUpdate()`, `verifyPlanPreconditions()`, `executePackUpdate()` with same-lifecycle TOCTOU fingerprint protection (source, installed owned files, relevant manifest state, overrides bytes). Stale plans abort with zero mutation.
+- `showdar inspect-pack <path> --checkpoint <file>` checkpoint compatibility explanation against the candidate effective catalog (current project + candidate pack + project overrides). Deterministic semantic reason codes (`workflow-missing`, `workflow-state-compat-unsupported`, `stage-removed`, `selected-stage-invalid`, `required-stage-conflict`, `skip-policy-invalid`, `recorded-skip-invalid`) with fixed precedence; malformed checkpoints report `schema-invalid` / `malformed-checkpoint`.
+- `showdar list --extensions --json` and `showdar doctor --extensions --json` using the common CLI envelope (`schemaVersion: 1`). Doctor reports `checkpointCompatibility: "not-assessed"` without a checkpoint. Diagnostics exit 0 on successful report.
+
+### Changed
+
+- `src/pack-update.js` refactored around canonical planning; v0.9 staged replacement and rollback safety preserved.
+- `list --extensions` human output now shows pack health status and pack profiles.
+- `create-pack` skill scaffold cleaned up (full required sections, substantive guidance, no filler) with validation guidance output.
+- TOCTOU lifecycle clarified: `--dry-run` is a read-only snapshot, not an authorization token. A later `update-pack` re-plans from current state. Stale-plan protection applies within a single execution lifecycle (`planPackUpdate` → `verifyPlanPreconditions` → `executePackUpdate`).
+
+### Fixed
+
+- `inspectCustomWorkflows` read `validateCustomWorkflowDoc` as `{ok, errors}` but the validator returns an error array, so `valid` was always `undefined` and doctor reported every workflow invalid. Now maps `errors.length === 0` to `valid`. Internal helper shape only; public CLI output unchanged.
+- `executePackUpdate` referenced undefined `manifestPath`; now resolves the project manifest path before writing. Covered by real update-path regression test.
+
+### Compatibility / Safety
+
+- v0.9 `validate-pack --json` (`{ok, errors}`) and plain `inspect-pack --json` shapes unchanged; backward-compat fixture tests added.
+- No persisted preview plans or tokens. No manifest v3, no workflow-state schema change, no WorkflowState key change.
+- Phase 6G authority, 15 primitives, 4 workflows, 6 profiles, 10 trace events frozen.
+- Dry-run is a snapshot, not a stored plan. No migration required. No tarball, remote registry, or executable plugins.
+
 ## [0.9.0]
 
 ### Added

package/README.md

@@ -570,23 +570,47 @@ executable hooks, lifecycle scripts, or remote code.
 ```bash
 showdar create-pack <path> [--vendor <v>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]
 showdar validate-pack <local-path> [--json]
-showdar inspect-pack <local-path> [--json]
+showdar inspect-pack <local-path> [--json] [--checkpoint <file>]
 ```
 
 **Install & lifecycle**
 
 ```bash
 showdar add-pack <local-path>
-showdar list --extensions
+showdar list --extensions [--json]
 showdar remove-pack <name>
-showdar update-pack <local-path>
+showdar update-pack <local-path> [--dry-run] [--json]
 ```
 
 **Diagnostics**
 
 ```bash
-showdar doctor --extensions
-```
+showdar doctor --extensions [--json]
+```
+
+`update-pack --dry-run` previews changes without mutation: file add/replace/remove
+counts, descriptive change categories (`source-only`, `skill-content`,
+`workflow-definition`, `profile-definition`, `metadata`, `reference`,
+`ownership`, `installed-drift`), ownership conflicts, and whether the update is
+currently executable. Categories are descriptive only and never claim checkpoint
+compatibility. The preview is a read-only snapshot, not an authorization token:
+a later `update-pack` re-plans from current state. Within a single update
+execution, if source, installed files, manifest, or overrides change between
+planning and applying that same plan, execution aborts as a stale plan with
+zero mutation.
+
+`inspect-pack --checkpoint` validates a workflow checkpoint against the candidate
+effective catalog (current project state + candidate pack + project overrides) and
+reports `compatible`, `workflow-incompatible` (with deterministic reason code and
+`replanRequired`), or `malformed`. Malformed checkpoints report `schema-invalid` /
+`malformed-checkpoint`, never `workflow-incompatible`.
+
+`list --extensions --json` and `doctor --extensions --json` use the common CLI
+envelope (`schemaVersion: 1`, `command`, `ok`, `data`, `warnings`, `errors`).
+Existing `validate-pack --json` and plain `inspect-pack --json` shapes are
+unchanged. `doctor` without a checkpoint reports `checkpointCompatibility:
+"not-assessed"`. Diagnostics exit 0 when they successfully report state, even when
+unhealthy; validation and execution failures exit 1.
 
 **Pack metadata**
 

package/bin/showdar.js

@@ -4,7 +4,9 @@ import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
-import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, removeGlobal, removePack, removeProject, validatePackSource, createPack, inspectPack, doctor, updatePack, readProjectOverrides } from '../src/project.js';
+import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, listExtensionsDetailed, removeGlobal, removePack, removeProject, validatePackSource, createPack, inspectPack, doctor, updatePack, readProjectOverrides } from '../src/project.js';
+import { formatPlanPreviewHuman, projectPackUpdatePreview } from '../src/pack-plan.js';
+import { assessCheckpointAgainstCandidate } from '../src/pack-inspect.js';
 import { validateRepository } from '../src/validate.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -43,7 +45,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json]\n  showdar doctor ${scopeUsage}\n  showdar update-pack <local-path>\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -63,11 +65,20 @@ async function main() {
 
   if (command === 'list') {
     if (args.includes('--extensions')) {
-      const result = await listExtensions({ cwd: projectRoot });
+      const isJson = args.includes('--json');
+      const result = await listExtensionsDetailed({ cwd: projectRoot });
+      if (isJson) {
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'list', ok: true, data: result, warnings: [], errors: [] }, null, 2));
+        return;
+      }
       console.log('Packs:');
-      for (const pack of result.packs) console.log(`  ${pack.name}@${pack.version}  ${pack.hash}`);
+      for (const pack of result.packs) console.log(`  ${pack.name}@${pack.version}  ${pack.status ?? 'healthy'}  ${pack.hash}`);
       console.log('Custom workflows:');
       for (const workflow of result.customWorkflows) console.log(`  ${workflow.id}  [${workflow.source}]  ${workflow.path}`);
+      if (result.profiles?.length) {
+        console.log('Pack profiles:');
+        for (const profile of result.profiles) console.log(`  ${profile.name}  [${profile.source}]  members: ${(profile.members ?? []).join(', ')}`);
+      }
       console.log(`Project overrides: ${result.overrides.present ? result.overrides.status : 'absent'}`);
       return;
     }
@@ -140,6 +151,31 @@ async function main() {
   }
 
   if (command === 'status' || command === 'doctor') {
+    if (command === 'doctor' && args.includes('--extensions')) {
+      const isJson = args.includes('--json');
+      const result = await doctor({ cwd: projectRoot });
+      if (isJson) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: 'doctor',
+          ok: true,
+          data: { ...result, checkpointCompatibility: 'not-assessed' },
+          warnings: result.warnings ?? [],
+          errors: [],
+        }, null, 2));
+        return;
+      }
+      console.log(`Extension diagnostics\nHealth: ${result.healthy ? 'OK' : 'BROKEN'}`);
+      for (const pack of result.packs) console.log(`  ${pack.name}@${pack.version}  ${pack.drift}`);
+      for (const wf of result.customWorkflows) console.log(`  workflow ${wf.id}: ${wf.valid ? 'valid' : 'invalid'}`);
+      for (const issue of result.issues) console.log(`- ${issue}`);
+      for (const warning of result.warnings ?? []) console.log(`warning: ${warning}`);
+      if (!result.healthy) {
+        console.log(`Checkpoint compatibility: not-assessed (supply a checkpoint via inspect-pack --checkpoint)`);
+        if (result.customWorkflows.length) console.log(`Note: checkpoints referencing changed workflow definitions will be revalidated on resume.`);
+      }
+      return;
+    }
     const result = scope === 'global' ? await inspectGlobal() : await inspectProject(projectRoot);
     if (!result.installed) {
       console.log(`Showdar Skills is not installed in the ${scope} scope.`);
@@ -213,8 +249,31 @@ async function main() {
 
   if (command === 'inspect-pack') {
     const packPath = args[1];
-    if (!packPath) throw new Error('Pack path is required. Usage: showdar inspect-pack <local-path> [--json]');
+    if (!packPath) throw new Error('Pack path is required. Usage: showdar inspect-pack <local-path> [--json] [--checkpoint <file>]');
     const isJson = args.includes('--json');
+    const checkpointIdx = args.indexOf('--checkpoint');
+    const checkpointFile = checkpointIdx === -1 ? null : args[checkpointIdx + 1];
+    if (checkpointIdx !== -1 && (!checkpointFile || checkpointFile.startsWith('--'))) {
+      throw new Error('--checkpoint requires a file path');
+    }
+    if (checkpointFile) {
+      const { readFile } = await import('node:fs/promises');
+      const checkpoint = await readFile(path.resolve(projectRoot, checkpointFile), 'utf8');
+      const assessment = await assessCheckpointAgainstCandidate({ cwd: projectRoot, candidatePath: path.resolve(projectRoot, packPath), checkpoint });
+      if (isJson) {
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'inspect-pack', ok: true, data: { checkpoint: assessment }, warnings: [], errors: [] }, null, 2));
+        return;
+      }
+      if (assessment.compatible) {
+        console.log(`Checkpoint compatibility: compatible\nReplan required: no`);
+        return;
+      }
+      console.log(`Checkpoint compatibility: ${assessment.category === 'schema-invalid' ? 'malformed' : 'workflow-incompatible'}\nReplan required: ${assessment.replanRequired ? 'yes' : 'no'}\nCategory: ${assessment.category}\nReason: ${assessment.reason}\nDetail: ${assessment.detail}`);
+      if (assessment.affectedWorkflow) console.log(`Affected workflow: ${assessment.affectedWorkflow}`);
+      if (assessment.affectedStage) console.log(`Affected stage: ${assessment.affectedStage}`);
+      console.log(`\nRun \`showdar update-pack <path> --dry-run\` to preview update.`);
+      return;
+    }
     const result = await inspectPack({ cwd: projectRoot, source: packPath });
     if (isJson) {
       console.log(JSON.stringify(result, null, 2));
@@ -246,9 +305,38 @@ async function main() {
 
   if (command === 'update-pack') {
     const packSource = args[1];
-    if (!packSource) throw new Error('Pack source is required. Usage: showdar update-pack <local-path>');
-    const result = await updatePack({ cwd: projectRoot, source: packSource });
-    console.log(`Showdar pack ${result.status}.\nPack: ${result.pack}\nVersion: ${result.version}${result.oldHash ? `\nOld hash: ${result.oldHash}\nNew hash: ${result.newHash}` : ''}\nFiles: ${result.files}`);
+    if (!packSource) throw new Error('Pack source is required. Usage: showdar update-pack <local-path> [--dry-run] [--json]');
+    const dryRun = args.includes('--dry-run');
+    const isJson = args.includes('--json');
+    if (dryRun) {
+      const { planPackUpdate } = await import('../src/pack-plan.js');
+      const plan = await planPackUpdate({ cwd: projectRoot, source: packSource });
+      if (isJson) {
+        console.log(JSON.stringify(projectPackUpdatePreview(plan), null, 2));
+        if (!plan.ok || !plan.executable) process.exitCode = 1;
+        return;
+      }
+      console.log(formatPlanPreviewHuman(plan));
+      if (!plan.ok || !plan.executable) process.exitCode = 1;
+      return;
+    }
+    if (isJson) {
+      try {
+        const result = await updatePack({ cwd: projectRoot, source: packSource });
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'update-pack', ok: true, data: result, warnings: result.plan?.warnings ?? [], errors: [] }, null, 2));
+      } catch (error) {
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'update-pack', ok: false, data: null, warnings: [], errors: [{ category: 'drift-detected', code: 'DRIFT_DETECTED', message: error.message }] }, null, 2));
+        process.exitCode = 1;
+      }
+      return;
+    }
+    try {
+      const result = await updatePack({ cwd: projectRoot, source: packSource });
+      console.log(`Showdar pack ${result.status}.\nPack: ${result.pack}\nVersion: ${result.version}${result.oldHash ? `\nOld hash: ${result.oldHash}\nNew hash: ${result.newHash}` : ''}\nFiles: ${result.files}`);
+    } catch (error) {
+      console.error(`showdar: ${error.message}`);
+      process.exitCode = 1;
+    }
     return;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

package/src/pack-compat.js

@@ -0,0 +1,197 @@
+import { createExtensionCatalog } from './extension-catalog.js';
+import { validateWorkflowState } from './workflow-state.js';
+
+export const COMPATIBILITY_REASONS = Object.freeze({
+  WORKFLOW_MISSING: 'workflow-missing',
+  WORKFLOW_STATE_COMPAT_UNSUPPORTED: 'workflow-state-compat-unsupported',
+  STAGE_REMOVED: 'stage-removed',
+  SELECTED_STAGE_INVALID: 'selected-stage-invalid',
+  REQUIRED_STAGE_CONFLICT: 'required-stage-conflict',
+  SKIP_POLICY_INVALID: 'skip-policy-invalid',
+  RECORDED_SKIP_INVALID: 'recorded-skip-invalid',
+});
+
+export const MALFORMED_REASON = 'malformed-checkpoint';
+
+const REASON_PRECEDENCE = Object.freeze([
+  'workflow-missing',
+  'workflow-state-compat-unsupported',
+  'stage-removed',
+  'selected-stage-invalid',
+  'required-stage-conflict',
+  'skip-policy-invalid',
+  'recorded-skip-invalid',
+]);
+
+const REMEDIATION_MESSAGES = Object.freeze({
+  'workflow-missing': 'Workflow no longer exists in the current candidate catalog.',
+  'workflow-state-compat-unsupported': 'Checkpoint uses unsupported workflowStateCompat schema version.',
+  'stage-removed': 'Selected stage is no longer declared by the workflow.',
+  'selected-stage-invalid': 'Selected stage is not a valid candidate stage.',
+  'required-stage-conflict': 'Required stage is not selected.',
+  'skip-policy-invalid': 'Skip rule for stage is not in workflow policy.',
+  'recorded-skip-invalid': 'Recorded skip reason or policy is no longer accepted.',
+  'malformed-checkpoint': 'Checkpoint cannot be parsed or fails schema validation.',
+});
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export async function assessCompatibilityReasons(checkpoint, catalog) {
+  let parsed = checkpoint;
+  if (typeof checkpoint === 'string') {
+    try {
+      parsed = JSON.parse(checkpoint);
+    } catch {
+      return {
+        compatible: false,
+        replanRequired: true,
+        category: 'schema-invalid',
+        reason: MALFORMED_REASON,
+        detail: REMEDIATION_MESSAGES[MALFORMED_REASON],
+        affectedWorkflow: null,
+        affectedStage: null,
+      };
+    }
+  }
+
+  if (!isRecord(parsed)) {
+    return {
+      compatible: false,
+      replanRequired: true,
+      category: 'schema-invalid',
+      reason: MALFORMED_REASON,
+      detail: REMEDIATION_MESSAGES[MALFORMED_REASON],
+      affectedWorkflow: null,
+      affectedStage: null,
+    };
+  }
+
+  const workflowId = parsed.workflowId;
+  const catalogStages = catalog?.selectableStages?.[workflowId] ?? null;
+  if (typeof workflowId !== 'string' || !catalogStages) {
+    return {
+      compatible: false,
+      replanRequired: true,
+      category: 'workflow-incompatible',
+      reason: 'workflow-missing',
+      detail: `${REMEDIATION_MESSAGES['workflow-missing']} Workflow: ${workflowId ?? 'unknown'}`,
+      affectedWorkflow: workflowId ?? null,
+      affectedStage: null,
+    };
+  }
+
+  const validation = validateWorkflowState(parsed, { extensionCatalog: catalog });
+  if (validation.ok) {
+    return {
+      compatible: true,
+      replanRequired: false,
+      category: null,
+      reason: null,
+      detail: null,
+      affectedWorkflow: workflowId,
+      affectedStage: null,
+    };
+  }
+
+  const errors = validation.errors;
+  const reason = mapErrorsToReason(errors, parsed, catalog);
+  return {
+    compatible: false,
+    replanRequired: true,
+    category: 'workflow-incompatible',
+    reason: reason.code,
+    detail: reason.detail,
+    affectedWorkflow: workflowId,
+    affectedStage: reason.stage,
+  };
+}
+
+function mapErrorsToReason(errors, parsed, catalog) {
+  const errorText = errors.join('; ');
+  const workflowId = parsed.workflowId;
+
+  if (errorText.includes('workflowId must be one of')) {
+    return { code: 'workflow-missing', stage: null, detail: `${REMEDIATION_MESSAGES['workflow-missing']} Workflow: ${workflowId}` };
+  }
+
+  const doc = findWorkflowDoc(catalog, workflowId);
+  if (doc && doc.workflowStateCompat && doc.workflowStateCompat.schemaVersion !== 1) {
+    return { code: 'workflow-state-compat-unsupported', stage: null, detail: REMEDIATION_MESSAGES['workflow-state-compat-unsupported'] };
+  }
+
+  const stages = catalog.selectableStages[workflowId] ?? [];
+  for (const stage of parsed.selectedStages ?? []) {
+    if (!stages.includes(stage)) {
+      return {
+        code: 'stage-removed',
+        stage,
+        detail: `${REMEDIATION_MESSAGES['stage-removed']} Stage: ${stage}, workflow: ${workflowId}`,
+      };
+    }
+  }
+
+  for (const stage of parsed.selectedStages ?? []) {
+    if (!(parsed.candidateStages ?? []).includes(stage)) {
+      return {
+        code: 'selected-stage-invalid',
+        stage,
+        detail: `${REMEDIATION_MESSAGES['selected-stage-invalid']} Stage: ${stage}`,
+      };
+    }
+  }
+
+  for (const error of errors) {
+    if (error.includes('required stage')) {
+      const m = error.match(/required stage (\S+)/);
+      return {
+        code: 'required-stage-conflict',
+        stage: m ? m[1] : null,
+        detail: `${REMEDIATION_MESSAGES['required-stage-conflict']} ${error}`,
+      };
+    }
+  }
+
+  for (const error of errors) {
+    if (error.includes('not skippable') || error.includes('skipRules') || error.includes('skip rule')) {
+      return {
+        code: 'skip-policy-invalid',
+        stage: extractStage(error),
+        detail: `${REMEDIATION_MESSAGES['skip-policy-invalid']} ${error}`,
+      };
+    }
+  }
+
+  for (const error of errors) {
+    if (error.includes('skip reason') || error.includes('skip policy')) {
+      return {
+        code: 'recorded-skip-invalid',
+        stage: extractStage(error),
+        detail: `${REMEDIATION_MESSAGES['recorded-skip-invalid']} ${error}`,
+      };
+    }
+  }
+
+  return {
+    code: 'recorded-skip-invalid',
+    stage: null,
+    detail: `${REMEDIATION_MESSAGES['recorded-skip-invalid']} ${errors[0] ?? 'Unknown incompatibility'}`,
+  };
+}
+
+function findWorkflowDoc(catalog, workflowId) {
+  return null;
+}
+
+function extractStage(error) {
+  const m = error.match(/stage (\S+)/) || error.match(/for (\S+)/);
+  return m ? m[1].replace(/[.,;:'"]/g, '') : null;
+}
+
+export function validateReasonPrecedence(reasons) {
+  const indices = reasons.map((r) => REASON_PRECEDENCE.indexOf(r));
+  return indices.every((idx, i) => i === 0 || indices[i - 1] <= idx);
+}
+
+export { REASON_PRECEDENCE, REMEDIATION_MESSAGES };

package/src/pack-inspect.js

@@ -181,9 +181,9 @@ async function inspectCustomWorkflows(cwd, manifest) {
     try {
       const docPath = path.join(cwd, wf.path);
       const doc = JSON.parse(await readFile(docPath, 'utf8'));
-      const { validateCustomWorkflowDoc, validateCustomWorkflowId } = await import('./validate-pack.js');
-      const validation = validateCustomWorkflowDoc(doc, `workflow ${doc.id}`);
-      results.push({ id: wf.id, path: wf.path, source: wf.source, valid: validation.ok, errors: validation.errors });
+      const { validateCustomWorkflowDoc } = await import('./validate-pack.js');
+      const errors = validateCustomWorkflowDoc(doc, `workflow ${doc.id}`);
+      results.push({ id: wf.id, path: wf.path, source: wf.source, valid: errors.length === 0, errors });
     } catch (error) {
       results.push({ id: wf.id, path: wf.path, source: wf.source, valid: false, errors: [error.message] });
     }
@@ -257,32 +257,105 @@ async function assessWorkflowCompatibility(checkpoint, extensionCatalog) {
 async function listExtensionsWithDetails(cwd) {
   const manifest = await readManifest(path.join(cwd, '.showdar.json'), cwd);
   if (!manifest) return null;
-  
+
   const overrides = await import('./project.js').then(m => m.readProjectOverrides({ cwd })).catch(() => null);
   const overridesStatus = overrides ? 'valid' : 'absent';
-  
+
   const packs = [];
   for (const pack of manifest.extensions?.packs ?? []) {
     const installed = await inspectPackInstalled(cwd, pack.name, pack);
-    packs.push({ name: pack.name, version: pack.version, hash: pack.hash, drift: installed.drift, driftDetails: installed.driftDetails });
+    const status = installed.drift === 'no-drift' ? 'healthy'
+      : installed.drift === 'source-unavailable' ? 'source-unavailable'
+      : installed.drift === 'installed-file-drift' ? 'installed-drift'
+      : installed.drift === 'source-drift' ? 'source-drift'
+      : installed.drift;
+    packs.push({ name: pack.name, version: pack.version, hash: pack.hash, status, drift: installed.drift, driftDetails: installed.driftDetails });
   }
-  
+
   const customWorkflows = [];
   for (const wf of manifest.extensions?.customWorkflows ?? []) {
     customWorkflows.push({ id: wf.id, source: wf.source, path: wf.path });
   }
-  
-  return { packs, customWorkflows, overrides: { present: true, status: overridesStatus } };
+
+  const projectProfiles = [];
+  if (overrides?.profiles) {
+    for (const name of Object.keys(overrides.profiles)) {
+      projectProfiles.push({ name, source: 'project-override', members: overrides.profiles[name] });
+    }
+  }
+  for (const pack of manifest.extensions?.packs ?? []) {
+    const packDir = path.join(cwd, EXTENSION_DIR, 'packs', pack.name);
+    try {
+      const packManifest = JSON.parse(await readFile(path.join(packDir, 'pack.json'), 'utf8'));
+      for (const [name, members] of Object.entries(packManifest.profiles ?? {})) {
+        projectProfiles.push({ name, source: `pack:${pack.name}`, members });
+      }
+    } catch {}
+  }
+
+  return { packs, customWorkflows, profiles: projectProfiles, overrides: { present: overrides !== null, status: overridesStatus } };
 }
 
-export { 
-  inspectPackSource, 
-  inspectPackInstalled, 
-  inspectCustomWorkflows, 
+async function buildCandidateEffectiveCatalog({ cwd, candidatePath }) {
+  const { createExtensionCatalog } = await import('./extension-catalog.js');
+  const manifestPath = path.join(cwd, '.showdar.json');
+  const manifest = await readManifest(manifestPath, cwd).catch(() => null);
+
+  const candidateManifest = await readPackManifest(candidatePath);
+  const candidateWorkflows = {};
+  for (const wf of candidateManifest.workflows ?? []) {
+    try {
+      candidateWorkflows[wf.id] = JSON.parse(await readFile(path.join(candidatePath, wf.path), 'utf8'));
+    } catch {}
+  }
+
+  const packs = [];
+  if (manifest) {
+    for (const pack of manifest.extensions?.packs ?? []) {
+      if (pack.name === candidateManifest.name) continue;
+      const packDir = path.join(cwd, EXTENSION_DIR, 'packs', pack.name);
+      try {
+        const pm = JSON.parse(await readFile(path.join(packDir, 'pack.json'), 'utf8'));
+        const workflows = {};
+        for (const wf of pm.workflows ?? []) {
+          try {
+            workflows[wf.id] = JSON.parse(await readFile(path.join(packDir, wf.path), 'utf8'));
+          } catch {}
+        }
+        packs.push({ manifest: pm, workflows });
+      } catch {}
+    }
+  }
+
+  packs.push({ manifest: candidateManifest, workflows: candidateWorkflows });
+
+  let projectOverrides = null;
+  try {
+    const { readProjectOverrides } = await import('./project.js');
+    projectOverrides = await readProjectOverrides({ cwd });
+  } catch {}
+
+  const result = createExtensionCatalog({ packs, projectOverrides });
+  if (!result.ok) throw new Error(`Candidate catalog invalid: ${result.errors.join('; ')}`);
+  return result.value;
+}
+
+async function assessCheckpointAgainstCandidate({ cwd, candidatePath, checkpoint }) {
+  const { assessCompatibilityReasons } = await import('./pack-compat.js');
+  const catalog = await buildCandidateEffectiveCatalog({ cwd, candidatePath });
+  return assessCompatibilityReasons(checkpoint, catalog);
+}
+
+export {
+  inspectPackSource,
+  inspectPackInstalled,
+  inspectCustomWorkflows,
   inspectOverrides,
   computePrecedence,
   assessWorkflowCompatibility,
   listExtensionsWithDetails,
+  buildCandidateEffectiveCatalog,
+  assessCheckpointAgainstCandidate,
   DRIFT_CATEGORIES,
 };
 
@@ -293,6 +366,8 @@ export const packInspectAPI = {
   computePrecedence,
   assessWorkflowCompatibility,
   listExtensionsWithDetails,
+  buildCandidateEffectiveCatalog,
+  assessCheckpointAgainstCandidate,
 };
 
 export default { inspectPackSource, inspectPackInstalled };