Spaces:
Runtime error
Runtime error
File size: 19,099 Bytes
a6b96c2 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 | "use strict";
/**
* Capability Writer — ADR-1213 write-side inverse of capability-state resolver.
*
* Exports:
* setCapabilityState(cwd, runtimeConfigDir, desired, opts?)
* → { capabilities: CapabilityStateEntry[], warnings: string[] }
* cmdCapabilitySet(cwd, runtimeConfigDir, capId, options, raw)
*
* Projection rules (three axes: install, surface, config):
* - enabled axis: mutates .gsd-surface.json via readSurface/writeSurface
* - gates axis: mutates .planning/config.json via setConfigValues (batched)
* - materialize: optionally calls applySurface to write skill files
* - re-resolve: always calls resolveCapabilityRuntimeState for the return value
*
* Dependencies (leaf modules only — no circular risk):
* - ./io.cjs (output, error)
* - ./capability-state.cjs (resolveCapabilityRuntimeState, _resolveManifest, _resolveCommandsGsdDir)
* - ./surface.cjs (readSurface, writeSurface, applySurface)
* - ./install-profiles.cjs (readActiveProfile)
* - ./config.cjs (setConfigValues)
* - ./runtime-artifact-layout.cjs (resolveRuntimeArtifactLayout)
* - capability-registry.cjs (loaded at call time)
*/
// eslint-disable-next-line @typescript-eslint/no-require-imports
const ioMod = require("./io.cjs");
const { output: coreOutput, error: coreError } = ioMod;
// eslint-disable-next-line @typescript-eslint/no-require-imports
const capabilityStateMod = require("./capability-state.cjs");
const { resolveCapabilityRuntimeState, _resolveManifest, _resolveCommandsGsdDir } = capabilityStateMod;
// eslint-disable-next-line @typescript-eslint/no-require-imports
const surfaceMod = require("./surface.cjs");
const { readSurface, writeSurface, applySurface } = surfaceMod;
// eslint-disable-next-line @typescript-eslint/no-require-imports
const installProfilesMod = require("./install-profiles.cjs");
const { readActiveProfile } = installProfilesMod;
// eslint-disable-next-line @typescript-eslint/no-require-imports
const configMod = require("./config.cjs");
const { setConfigValues } = configMod;
// eslint-disable-next-line @typescript-eslint/no-require-imports
const planningWorkspaceMod = require("./planning-workspace.cjs");
const { planningDir } = planningWorkspaceMod;
// eslint-disable-next-line @typescript-eslint/no-require-imports
const nodefs = require("fs");
// eslint-disable-next-line @typescript-eslint/no-require-imports
const nodepath = require("path");
// ─── Implementation ───────────────────────────────────────────────────────────
/**
* Write-side capability state mutator.
*
* Applies desired capability state changes (enabled axis via surface, gates
* axis via config) then re-resolves and returns the full capability state.
*
* Control flow:
* 1. RESOLVE BEFORE STATE: call resolveCapabilityRuntimeState once to get the
* canonical runtimeConfigDir and current capability state.
* 2. VALIDATION PASS (no writes): validate each desired entry against the
* registry and `before` state; collect errors and warnings.
* 3. If errors → return early with before.capabilities (no writes performed).
* 4. APPLY PASS: compute new surface state, writeSurface once if changed,
* setConfigValues once for gate writes; materialize if opts provided.
* 5. RE-RESOLVE: call resolveCapabilityRuntimeState again to get final state.
* 6. POST CHECKS: enabled=true but not-surfaced (not-in-profile) error;
* present-but-dead warning; append resolver warnings.
* 7. Return { capabilities: after.capabilities, warnings, errors }.
*/
function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
const warnings = [];
const errors = [];
// ── Step 1: Resolve BEFORE state once ────────────────────────────────────
const before = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
const resolvedConfigDir = before.runtimeConfigDir;
// ── Load registry ─────────────────────────────────────────────────────────
// eslint-disable-next-line @typescript-eslint/no-require-imports
const registry = require('./capability-registry.cjs');
const capabilitiesMap = (registry['capabilities'] && typeof registry['capabilities'] === 'object' && !Array.isArray(registry['capabilities'])
? registry['capabilities']
: {});
// ── Step 2: VALIDATION PASS (no writes) ──────────────────────────────────
// Accumulate all valid gate writes and surface deltas.
// If ANY error is found, we will return early without writing anything.
const pendingGateWrites = [];
// surface-delta accumulators: ids to add to / remove from disabledClusters
const idsToDisable = [];
const idsToEnable = [];
// Track which ids need surface loading (have skills + explicit enabled flag)
let needsSurface = false;
for (const entry of desired) {
const { id, enabled, gates } = entry;
// Validate capability id
if (!Object.prototype.hasOwnProperty.call(capabilitiesMap, id)) {
errors.push(`unknown capability: "${id}"`);
continue;
}
const capObj = capabilitiesMap[id];
const skillsRaw = capObj['skills'];
const skills = Array.isArray(skillsRaw)
? skillsRaw.filter((s) => typeof s === 'string')
: [];
const configDef = (capObj['config'] && typeof capObj['config'] === 'object' && !Array.isArray(capObj['config'])
? capObj['config']
: {});
// ── Validate gate keys / values ──────────────────────────────────────────
if (gates !== undefined) {
for (const [key, val] of Object.entries(gates)) {
if (!Object.prototype.hasOwnProperty.call(configDef, key)) {
errors.push(`unknown gate key "${key}" for capability "${id}"`);
continue;
}
if (typeof val !== 'boolean') {
errors.push(`gate value for "${key}" must be boolean, got ${typeof val}`);
continue;
}
pendingGateWrites.push({ keyPath: key, value: val });
}
}
// ── Validate enabled axis ────────────────────────────────────────────────
if (enabled !== undefined) {
if (skills.length === 0) {
// Advisory only — no surface effect possible
warnings.push(`capability "${id}" owns no skills; 'enabled' has no surface effect — use gates to toggle its hooks`);
continue;
}
// Install-floor check: cannot enable a capability whose skills are not installed
if (enabled === true) {
const beforeEntry = before.capabilities.find((c) => c.id === id);
if (beforeEntry && beforeEntry.installed === false) {
errors.push(`cannot enable "${id}": its skills are not in the install profile`);
continue;
}
}
needsSurface = true;
if (enabled === false) {
idsToDisable.push(id);
}
else {
idsToEnable.push(id);
}
}
}
// ── Fix D: Pre-validate config.json parseability before any write ────────
// If there are pending gate writes, attempt to read and parse the target
// config.json BEFORE writing anything. A malformed file would cause
// setConfigValues to error() mid-operation leaving a partial write.
if (pendingGateWrites.length > 0) {
try {
const configJsonPath = nodepath.join(planningDir(cwd), 'config.json');
if (nodefs.existsSync(configJsonPath)) {
const raw = nodefs.readFileSync(configJsonPath, 'utf-8');
try {
JSON.parse(raw);
}
catch (parseErr) {
const msg = parseErr instanceof Error ? parseErr.message : String(parseErr);
errors.push(`config.json is malformed: ${msg}`);
}
}
}
catch {
// Cannot read the file path — not an error (e.g. planningDir env-var issue); let setConfigValues handle it
}
}
// ── Step 3: Early return on validation errors ────────────────────────────
if (errors.length > 0) {
return {
capabilities: before.capabilities,
warnings,
errors,
};
}
// ── Step 4: APPLY PASS ────────────────────────────────────────────────────
// ── Surface writes ────────────────────────────────────────────────────────
if (needsSurface && (idsToDisable.length > 0 || idsToEnable.length > 0)) {
const existing = readSurface(resolvedConfigDir);
let pendingSurface = existing ?? {
baseProfile: readActiveProfile(resolvedConfigDir) ?? 'full',
disabledClusters: [],
explicitAdds: [],
explicitRemoves: [],
};
let surfaceChanged = false;
for (const id of idsToDisable) {
// Add id to disabledClusters (dedupe)
if (!pendingSurface.disabledClusters.includes(id)) {
pendingSurface = {
...pendingSurface,
disabledClusters: [...pendingSurface.disabledClusters, id],
};
surfaceChanged = true;
}
// Fix A: explicitAdds contains SKILL STEMS, not capability ids.
// Remove the capability's skill stems from explicitAdds so that
// resolveSurface does not re-add those skills after the cluster disable.
const capObjForDisable = capabilitiesMap[id];
const skillsRawForDisable = capObjForDisable?.['skills'];
const skillStemsForDisable = Array.isArray(skillsRawForDisable)
? skillsRawForDisable.filter((s) => typeof s === 'string')
: [];
const newExplicitAdds = pendingSurface.explicitAdds.filter((x) => !skillStemsForDisable.includes(x));
if (newExplicitAdds.length !== pendingSurface.explicitAdds.length) {
pendingSurface = { ...pendingSurface, explicitAdds: newExplicitAdds };
surfaceChanged = true;
}
}
for (const id of idsToEnable) {
// Remove id from disabledClusters
if (pendingSurface.disabledClusters.includes(id)) {
pendingSurface = {
...pendingSurface,
disabledClusters: pendingSurface.disabledClusters.filter((x) => x !== id),
};
surfaceChanged = true;
}
// Fix A (enable branch): also remove the capability's skill stems from
// explicitRemoves so that resolveSurface does not subtract those skills.
// Do NOT add anything to explicitAdds — a cap that was only in explicitAdds
// and was disabled is caught by the post-check below.
const capObjForEnable = capabilitiesMap[id];
const skillsRawForEnable = capObjForEnable?.['skills'];
const skillStemsForEnable = Array.isArray(skillsRawForEnable)
? skillsRawForEnable.filter((s) => typeof s === 'string')
: [];
const newExplicitRemoves = pendingSurface.explicitRemoves.filter((x) => !skillStemsForEnable.includes(x));
if (newExplicitRemoves.length !== pendingSurface.explicitRemoves.length) {
pendingSurface = { ...pendingSurface, explicitRemoves: newExplicitRemoves };
surfaceChanged = true;
}
}
if (surfaceChanged) {
writeSurface(resolvedConfigDir, pendingSurface);
}
}
// ── Config writes (once, batched) ─────────────────────────────────────────
if (pendingGateWrites.length > 0) {
setConfigValues(cwd, pendingGateWrites);
}
// ── Materialize (optional) ────────────────────────────────────────────────
if (opts?.materialize) {
const { runtime, scope } = opts.materialize;
try {
// eslint-disable-next-line @typescript-eslint/no-require-imports
const runtimeArtifactLayout = require('./runtime-artifact-layout.cjs');
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, resolvedConfigDir, scope);
const commandsGsdDir = _resolveCommandsGsdDir();
const manifest = _resolveManifest(commandsGsdDir, resolvedConfigDir);
// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
applySurface(resolvedConfigDir, layout, manifest, undefined, registry);
}
catch (err) {
const msg = err instanceof Error ? err.message : String(err);
// Fix C: materialise was explicitly requested — a failure is an error (non-zero exit),
// not merely advisory.
errors.push(`materialize failed: ${msg}`);
}
}
// ── Step 5: RE-RESOLVE ────────────────────────────────────────────────────
const after = resolveCapabilityRuntimeState(cwd, resolvedConfigDir);
// ── Step 6: POST CHECKS ───────────────────────────────────────────────────
// Check: desired enabled=true but not actually enabled after write
// (catches the not-in-profile / not-surfaced silent no-op case).
// The install-floor case (installed===false) was already caught in validation.
for (const entry of desired) {
if (entry.enabled === true) {
const afterCap = after.capabilities.find((c) => c.id === entry.id);
if (afterCap && afterCap.enabled !== true) {
errors.push(`cannot enable "${entry.id}": not in the active surface/profile (widen the profile or use /gsd:surface enable)`);
}
}
// Fix B: desired enabled=false — assert it is actually disabled after write.
// Prevents "off means off" silent failures (e.g. explicitAdds containing the
// cap's skill stems re-adds them after the cluster disable).
if (entry.enabled === false) {
const afterCap = after.capabilities.find((c) => c.id === entry.id);
if (afterCap && afterCap.enabled !== false) {
errors.push(`failed to disable "${entry.id}": still surfaced after write`);
}
}
}
// Check: present-but-dead — SCOPED to touched (desired) capabilities only.
const desiredIds = new Set(desired.map((d) => d.id));
for (const cap of after.capabilities) {
if (!desiredIds.has(cap.id))
continue;
if (cap.enabled === true &&
cap.hooks.length > 0 &&
cap.hooks.every((h) => !h.configured)) {
warnings.push(`capability "${cap.id}" is surfaced but every hook is gated off — did you mean enabled:false?`);
}
}
// Append resolver's own warnings
for (const w of after.warnings) {
warnings.push(w);
}
return {
capabilities: after.capabilities,
warnings,
errors,
};
}
/**
* CLI command entry point for `gsd-tools capability set`.
*
* Builds one DesiredCapability from the provided options, calls setCapabilityState,
* then prints the result. When raw=true emits JSON; else emits a human summary.
* Warnings are always printed to stderr.
*/
function cmdCapabilitySet(cwd, runtimeConfigDir, capId, options, raw) {
const desired = [
{
id: capId,
...(options.enabled !== undefined ? { enabled: options.enabled } : {}),
...(options.gates ? { gates: options.gates } : {}),
},
];
const opts = options.runtime
? { materialize: { runtime: options.runtime, scope: options.scope ?? 'global' } }
: undefined;
const result = setCapabilityState(cwd, runtimeConfigDir, desired, opts);
if (raw) {
// Raw mode: emit JSON to stdout including errors; exit non-zero if errors present.
// Do NOT print human stderr lines — raw consumers parse the JSON.
coreOutput({ capabilities: result.capabilities, warnings: result.warnings, errors: result.errors }, true);
if (result.errors.length > 0) {
process.exit(1);
}
return;
}
// Human mode: print warnings and errors to stderr (non-fatally for warnings).
for (const w of result.warnings) {
process.stderr.write(`capability set: warning: ${w}\n`);
}
for (const e of result.errors) {
process.stderr.write(`capability set: error: ${e}\n`);
}
// Exit non-zero if any errors (hard failures — requested action was not realized).
if (result.errors.length > 0) {
coreError(`capability set: ${String(result.errors.length)} error(s) — see above`);
return; // unreachable — coreError calls process.exit(1)
}
// Human-readable summary: focus on the target capability
const cap = result.capabilities.find((c) => c.id === capId);
if (!cap) {
const msg = `capability "${capId}" not found in registry`;
coreOutput(msg, false, msg);
return;
}
const activeHooks = cap.hooks.filter((h) => h.active).length;
const summary = `capability ${capId}: enabled=${String(cap.enabled)}, surfaced=${String(cap.surfaced)}, installed=${String(cap.installed)}, activeHooks=${String(activeHooks)}/${String(cap.hooks.length)}`;
coreOutput({ id: cap.id, enabled: cap.enabled, surfaced: cap.surfaced, installed: cap.installed, warnings: result.warnings.length > 0 ? result.warnings : undefined }, false, summary);
}
module.exports = {
setCapabilityState,
cmdCapabilitySet,
};
|