harness-everything 0.36.2 → 0.36.3

package/plugins/harness-everything/skills/to-spec/scripts/check-project-docs.js

@@ -37,7 +37,7 @@ const fs = require('fs');
 const path = require('path');
 // Keep project-doc path decisions in the resolver carried by the installed
 // multi-agent-workspace skill. This script consumes the same contract.
-const { getWorkspaceRoot, getRepoManifestHomes, detectProjectDocsConventions, validateDocsConfig } =
+const { getWorkspaceRoot, getRepoManifestHomes, detectProjectDocsConventions, validateDocsConfig, normalizeHostProjectDocs } =
   require('./project-docs-resolver');
 
 function loadManifestHelper() {
@@ -150,6 +150,75 @@ function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
+function isPathInside(rootPath, candidatePath) {
+  const relativePath = path.relative(rootPath, candidatePath);
+  return relativePath === '' || (
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relativePath)
+  );
+}
+
+function inspectInitPath(workspaceRoot, targetPath) {
+  let realWorkspaceRoot;
+  try {
+    realWorkspaceRoot = fs.realpathSync(workspaceRoot);
+  } catch (error) {
+    return { error: `workspace root cannot be resolved (${error.message})` };
+  }
+
+  try {
+    fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') return { error: `path cannot be inspected (${error.message})` };
+
+    let parentPath = path.dirname(targetPath);
+    while (true) {
+      try {
+        fs.lstatSync(parentPath);
+      } catch (parentError) {
+        if (parentError.code !== 'ENOENT') return { error: `parent cannot be inspected (${parentError.message})` };
+        const nextParent = path.dirname(parentPath);
+        if (nextParent === parentPath) return { error: 'no existing parent could be found' };
+        parentPath = nextParent;
+        continue;
+      }
+
+      let realParentPath;
+      try {
+        realParentPath = fs.realpathSync(parentPath);
+      } catch (parentError) {
+        return { error: `parent cannot be resolved (${parentError.message})` };
+      }
+      let parentStats;
+      try {
+        parentStats = fs.statSync(realParentPath);
+      } catch (parentError) {
+        return { error: `parent cannot be inspected (${parentError.message})` };
+      }
+      if (!parentStats.isDirectory()) return { error: 'cannot be read safely because its nearest existing parent is not a directory' };
+      if (!isPathInside(realWorkspaceRoot, realParentPath)) return { error: 'nearest existing parent resolves outside the workspace' };
+      return { exists: false };
+    }
+  }
+
+  let realTargetPath;
+  try {
+    realTargetPath = fs.realpathSync(targetPath);
+  } catch (error) {
+    return { error: `path cannot be resolved (${error.message})` };
+  }
+  let targetStats;
+  try {
+    targetStats = fs.statSync(realTargetPath);
+  } catch (error) {
+    return { error: `path cannot be inspected (${error.message})` };
+  }
+  if (!targetStats.isFile()) return { error: 'cannot be read because it is not a regular file' };
+  if (!isPathInside(realWorkspaceRoot, realTargetPath)) return { error: 'resolves outside the workspace' };
+  return { exists: true };
+}
+
 // init never overwrites a configured value: absent/empty required fields are
 // filled, matching flags are accepted as no-ops, and a differing flag is a
 // field-specific conflict that aborts before any write.
@@ -179,6 +248,65 @@ function printConflicts(conflicts) {
   }
 }
 
+function readHostManifestForInit(workspaceRoot, manifestPath) {
+  const inspected = inspectInitPath(workspaceRoot, manifestPath);
+  if (inspected.error) return { error: `unsafe path: ${inspected.error}` };
+  if (!inspected.exists) return { exists: false, data: readManifest(manifestPath) };
+
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8');
+  } catch (error) {
+    return { error: `cannot be read (${error.message})` };
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    return { error: `invalid JSON (${error.message})` };
+  }
+  if (!isPlainObject(data)) return { error: 'manifest root must be a JSON object' };
+
+  for (const field of ['skills', 'agents', 'generated']) {
+    if (Object.prototype.hasOwnProperty.call(data, field) && !Array.isArray(data[field])) {
+      return { error: `manifest ${field} must be an array` };
+    }
+  }
+  if (!Array.isArray(data.skills)) data.skills = [];
+  if (!Array.isArray(data.agents)) data.agents = [];
+
+  if (Object.prototype.hasOwnProperty.call(data, 'projectDocs')) {
+    const normalizedProjectDocs = normalizeHostProjectDocs(data.projectDocs).projectDocs;
+    const validation = validateDocsConfig(normalizedProjectDocs);
+    if (!validation.valid) {
+      const details = validation.diagnostics.map(item => `${item.code}: ${item.message}`).join('; ');
+      return { error: `projectDocs failed schema validation (${details})` };
+    }
+  }
+
+  return { exists: true, data };
+}
+
+function rejectHostManifestInit(workspaceRoot, manifestPath, reason) {
+  const relativePath = path.relative(workspaceRoot, manifestPath).replace(/\\/g, '/');
+  console.error(`[Project Docs Check] ${relativePath} cannot be safely updated: ${reason}; no host manifests were changed.`);
+  const guidance = reason.startsWith('cannot be read') || reason.includes('not a regular file')
+    ? `Make ${relativePath} a readable manifest file (not a directory), then rerun init.`
+    : reason.startsWith('unsafe path')
+      ? `Make ${relativePath} a regular file that resolves inside this workspace, then rerun init.`
+    : `Repair the JSON structure or projectDocs schema in ${relativePath}, then rerun init.`;
+  console.error(`=> ${guidance}`);
+  process.exit(1);
+}
+
+function rejectProjectFileInit(workspaceRoot, projectFile, reason) {
+  const relativePath = path.relative(workspaceRoot, projectFile).replace(/\\/g, '/');
+  console.error(`[Project Docs Check] ${relativePath} cannot be safely updated: unsafe path (${reason}); no files were changed.`);
+  console.error(`=> Make ${relativePath} a regular file that resolves inside this workspace, then rerun init.`);
+  process.exit(1);
+}
+
 function runInit(workspaceRoot, args) {
   const flags = parseFlags(args);
   // Required values must be non-empty after trimming, the same presence rule
@@ -205,7 +333,9 @@ function runInit(workspaceRoot, args) {
   // the authoritative repair target: fill only its absent/empty fields,
   // preserve every other key, validate the candidate, and write only it.
   const projectFile = path.join(workspaceRoot, '.agents', 'harness-everything', 'project-docs.json');
-  if (fs.existsSync(projectFile)) {
+  const projectFilePath = inspectInitPath(workspaceRoot, projectFile);
+  if (projectFilePath.error) rejectProjectFileInit(workspaceRoot, projectFile, projectFilePath.error);
+  if (projectFilePath.exists) {
     const rel = path.relative(workspaceRoot, projectFile).replace(/\\/g, '/');
     let existing;
     try {
@@ -252,8 +382,10 @@ function runInit(workspaceRoot, args) {
   const writableHomes = [];
   for (const home of homes) {
     const manifestPath = getManifestPath(home);
-    if (!fs.existsSync(path.dirname(manifestPath))) continue;
-    const data = readManifest(manifestPath);
+    const result = readHostManifestForInit(workspaceRoot, manifestPath);
+    if (result.error) rejectHostManifestInit(workspaceRoot, manifestPath, result.error);
+    if (!result.exists && !fs.existsSync(path.dirname(manifestPath))) continue;
+    const data = result.data;
     const existingProjectDocs = isPlainObject(data.projectDocs) ? data.projectDocs : null;
     writableHomes.push({ manifestPath, data, existingProjectDocs });
   }

package/plugins/harness-everything/skills/to-spec/scripts/project-docs-resolver.js

@@ -78,6 +78,25 @@ function isPlainObject(value) {
   return prototype === Object.prototype || prototype === null;
 }
 
+function normalizeHostProjectDocs(projectDocs) {
+  if (!isPlainObject(projectDocs)) return { projectDocs, warnings: [] };
+
+  const normalized = { ...projectDocs };
+  const warnings = [];
+  if (typeof normalized.domains === 'string') {
+    if (typeof normalized.domainLocation !== 'string' || !normalized.domainLocation.trim()) {
+      normalized.domainLocation = normalized.domains;
+    }
+    delete normalized.domains;
+    warnings.push({
+      code: 'deprecated-domains-string',
+      severity: 'warning',
+      message: 'host projectDocs.domains as a string is deprecated; use domainLocation for the zone path and domains as the ID-prefix array'
+    });
+  }
+  return { projectDocs: normalized, warnings };
+}
+
 function projectDocsConfigPath(workspaceRoot) {
   return path.join(workspaceRoot, PROJECT_DOCS_CONFIG);
 }
@@ -148,22 +167,12 @@ function inspectHostProjectDocs(workspaceRoot) {
       continue;
     }
 
-    const projectDocs = { ...manifest.projectDocs };
-    if (typeof projectDocs.domains === 'string') {
-      if (typeof projectDocs.domainLocation !== 'string' || !projectDocs.domainLocation.trim()) {
-        projectDocs.domainLocation = projectDocs.domains;
-      }
-      delete projectDocs.domains;
-      entry.warnings.push({
-        code: 'deprecated-domains-string',
-        severity: 'warning',
-        path: configSource(workspaceRoot, file),
-        message: 'host projectDocs.domains as a string is deprecated; use domainLocation for the zone path and domains as the ID-prefix array'
-      });
-    }
+    const normalizedHost = normalizeHostProjectDocs(manifest.projectDocs);
+    const projectDocs = normalizedHost.projectDocs;
 
     const validation = validateDocsConfig(projectDocs);
     const source = configSource(workspaceRoot, file);
+    entry.warnings.push(...normalizedHost.warnings.map(item => ({ ...item, path: source })));
     entry.warnings.push(...validation.warnings.map(item => ({ ...item, path: source })));
     if (!validation.valid) {
       const details = validation.diagnostics.map(item => item.message).join('; ');
@@ -236,6 +245,13 @@ function validateDocsConfig(config) {
     return { valid: false, diagnostics, warnings };
   }
 
+  for (const field of ['docLocation', 'tracker', 'issueDefinition']) {
+    if (config[field] !== undefined && typeof config[field] !== 'string') {
+      const diagnosticField = field.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+      invalid(`invalid-${diagnosticField}-type`, `${field} must be a string when provided`);
+    }
+  }
+
   for (const key of Object.keys(config).sort()) {
     if (!PROJECT_DOC_CONFIG_KEYS.has(key)) {
       warnings.push({
@@ -754,6 +770,7 @@ module.exports = {
   readProjectDocs,
   resolveDocsConfig,
   validateDocsConfig,
+  normalizeHostProjectDocs,
   parseContextMap,
   resolveProjectDocs,
   detectProjectDocsConventions,

package/sbom.cdx.json

@@ -2,23 +2,23 @@
   "$schema": "https://cyclonedx.org/schema/bom-1.7.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.7",
-  "serialNumber": "urn:uuid:d784e4c6-dc73-508d-9e04-a38908e96486",
+  "serialNumber": "urn:uuid:f2d00cc7-b0ba-5fb7-aa66-45210b7b3234",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-10-20T05:31:16.491Z",
+    "timestamp": "2026-10-20T14:22:39.675Z",
     "tools": [
       {
         "vendor": "Harness Everything",
         "name": "generate-sbom.js",
-        "version": "0.36.2"
+        "version": "0.36.3"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/harness-everything@0.36.2",
+      "bom-ref": "pkg:npm/harness-everything@0.36.3",
       "name": "harness-everything",
-      "version": "0.36.2",
-      "purl": "pkg:npm/harness-everything@0.36.2"
+      "version": "0.36.3",
+      "purl": "pkg:npm/harness-everything@0.36.3"
     }
   },
   "components": [
@@ -1999,7 +1999,7 @@
       ]
     },
     {
-      "ref": "pkg:npm/harness-everything@0.36.2",
+      "ref": "pkg:npm/harness-everything@0.36.3",
       "dependsOn": [
         "pkg:npm/%40commitlint/cli@19.8.1",
         "pkg:npm/%40commitlint/config-conventional@19.8.1",

package/to-spec/SKILL.md

@@ -4,7 +4,7 @@ description: "Turn the conversation into a written spec — feature PRD, CLI/API
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.34.0
+  version: 0.36.3
 ---
 
 # To Spec

package/to-spec/scripts/check-project-docs.js

@@ -37,7 +37,7 @@ const fs = require('fs');
 const path = require('path');
 // Keep project-doc path decisions in the resolver carried by the installed
 // multi-agent-workspace skill. This script consumes the same contract.
-const { getWorkspaceRoot, getRepoManifestHomes, detectProjectDocsConventions, validateDocsConfig } =
+const { getWorkspaceRoot, getRepoManifestHomes, detectProjectDocsConventions, validateDocsConfig, normalizeHostProjectDocs } =
   require('./project-docs-resolver');
 
 function loadManifestHelper() {
@@ -150,6 +150,75 @@ function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
+function isPathInside(rootPath, candidatePath) {
+  const relativePath = path.relative(rootPath, candidatePath);
+  return relativePath === '' || (
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relativePath)
+  );
+}
+
+function inspectInitPath(workspaceRoot, targetPath) {
+  let realWorkspaceRoot;
+  try {
+    realWorkspaceRoot = fs.realpathSync(workspaceRoot);
+  } catch (error) {
+    return { error: `workspace root cannot be resolved (${error.message})` };
+  }
+
+  try {
+    fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') return { error: `path cannot be inspected (${error.message})` };
+
+    let parentPath = path.dirname(targetPath);
+    while (true) {
+      try {
+        fs.lstatSync(parentPath);
+      } catch (parentError) {
+        if (parentError.code !== 'ENOENT') return { error: `parent cannot be inspected (${parentError.message})` };
+        const nextParent = path.dirname(parentPath);
+        if (nextParent === parentPath) return { error: 'no existing parent could be found' };
+        parentPath = nextParent;
+        continue;
+      }
+
+      let realParentPath;
+      try {
+        realParentPath = fs.realpathSync(parentPath);
+      } catch (parentError) {
+        return { error: `parent cannot be resolved (${parentError.message})` };
+      }
+      let parentStats;
+      try {
+        parentStats = fs.statSync(realParentPath);
+      } catch (parentError) {
+        return { error: `parent cannot be inspected (${parentError.message})` };
+      }
+      if (!parentStats.isDirectory()) return { error: 'cannot be read safely because its nearest existing parent is not a directory' };
+      if (!isPathInside(realWorkspaceRoot, realParentPath)) return { error: 'nearest existing parent resolves outside the workspace' };
+      return { exists: false };
+    }
+  }
+
+  let realTargetPath;
+  try {
+    realTargetPath = fs.realpathSync(targetPath);
+  } catch (error) {
+    return { error: `path cannot be resolved (${error.message})` };
+  }
+  let targetStats;
+  try {
+    targetStats = fs.statSync(realTargetPath);
+  } catch (error) {
+    return { error: `path cannot be inspected (${error.message})` };
+  }
+  if (!targetStats.isFile()) return { error: 'cannot be read because it is not a regular file' };
+  if (!isPathInside(realWorkspaceRoot, realTargetPath)) return { error: 'resolves outside the workspace' };
+  return { exists: true };
+}
+
 // init never overwrites a configured value: absent/empty required fields are
 // filled, matching flags are accepted as no-ops, and a differing flag is a
 // field-specific conflict that aborts before any write.
@@ -179,6 +248,65 @@ function printConflicts(conflicts) {
   }
 }
 
+function readHostManifestForInit(workspaceRoot, manifestPath) {
+  const inspected = inspectInitPath(workspaceRoot, manifestPath);
+  if (inspected.error) return { error: `unsafe path: ${inspected.error}` };
+  if (!inspected.exists) return { exists: false, data: readManifest(manifestPath) };
+
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8');
+  } catch (error) {
+    return { error: `cannot be read (${error.message})` };
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    return { error: `invalid JSON (${error.message})` };
+  }
+  if (!isPlainObject(data)) return { error: 'manifest root must be a JSON object' };
+
+  for (const field of ['skills', 'agents', 'generated']) {
+    if (Object.prototype.hasOwnProperty.call(data, field) && !Array.isArray(data[field])) {
+      return { error: `manifest ${field} must be an array` };
+    }
+  }
+  if (!Array.isArray(data.skills)) data.skills = [];
+  if (!Array.isArray(data.agents)) data.agents = [];
+
+  if (Object.prototype.hasOwnProperty.call(data, 'projectDocs')) {
+    const normalizedProjectDocs = normalizeHostProjectDocs(data.projectDocs).projectDocs;
+    const validation = validateDocsConfig(normalizedProjectDocs);
+    if (!validation.valid) {
+      const details = validation.diagnostics.map(item => `${item.code}: ${item.message}`).join('; ');
+      return { error: `projectDocs failed schema validation (${details})` };
+    }
+  }
+
+  return { exists: true, data };
+}
+
+function rejectHostManifestInit(workspaceRoot, manifestPath, reason) {
+  const relativePath = path.relative(workspaceRoot, manifestPath).replace(/\\/g, '/');
+  console.error(`[Project Docs Check] ${relativePath} cannot be safely updated: ${reason}; no host manifests were changed.`);
+  const guidance = reason.startsWith('cannot be read') || reason.includes('not a regular file')
+    ? `Make ${relativePath} a readable manifest file (not a directory), then rerun init.`
+    : reason.startsWith('unsafe path')
+      ? `Make ${relativePath} a regular file that resolves inside this workspace, then rerun init.`
+    : `Repair the JSON structure or projectDocs schema in ${relativePath}, then rerun init.`;
+  console.error(`=> ${guidance}`);
+  process.exit(1);
+}
+
+function rejectProjectFileInit(workspaceRoot, projectFile, reason) {
+  const relativePath = path.relative(workspaceRoot, projectFile).replace(/\\/g, '/');
+  console.error(`[Project Docs Check] ${relativePath} cannot be safely updated: unsafe path (${reason}); no files were changed.`);
+  console.error(`=> Make ${relativePath} a regular file that resolves inside this workspace, then rerun init.`);
+  process.exit(1);
+}
+
 function runInit(workspaceRoot, args) {
   const flags = parseFlags(args);
   // Required values must be non-empty after trimming, the same presence rule
@@ -205,7 +333,9 @@ function runInit(workspaceRoot, args) {
   // the authoritative repair target: fill only its absent/empty fields,
   // preserve every other key, validate the candidate, and write only it.
   const projectFile = path.join(workspaceRoot, '.agents', 'harness-everything', 'project-docs.json');
-  if (fs.existsSync(projectFile)) {
+  const projectFilePath = inspectInitPath(workspaceRoot, projectFile);
+  if (projectFilePath.error) rejectProjectFileInit(workspaceRoot, projectFile, projectFilePath.error);
+  if (projectFilePath.exists) {
     const rel = path.relative(workspaceRoot, projectFile).replace(/\\/g, '/');
     let existing;
     try {
@@ -252,8 +382,10 @@ function runInit(workspaceRoot, args) {
   const writableHomes = [];
   for (const home of homes) {
     const manifestPath = getManifestPath(home);
-    if (!fs.existsSync(path.dirname(manifestPath))) continue;
-    const data = readManifest(manifestPath);
+    const result = readHostManifestForInit(workspaceRoot, manifestPath);
+    if (result.error) rejectHostManifestInit(workspaceRoot, manifestPath, result.error);
+    if (!result.exists && !fs.existsSync(path.dirname(manifestPath))) continue;
+    const data = result.data;
     const existingProjectDocs = isPlainObject(data.projectDocs) ? data.projectDocs : null;
     writableHomes.push({ manifestPath, data, existingProjectDocs });
   }

package/to-spec/scripts/project-docs-resolver.js

@@ -78,6 +78,25 @@ function isPlainObject(value) {
   return prototype === Object.prototype || prototype === null;
 }
 
+function normalizeHostProjectDocs(projectDocs) {
+  if (!isPlainObject(projectDocs)) return { projectDocs, warnings: [] };
+
+  const normalized = { ...projectDocs };
+  const warnings = [];
+  if (typeof normalized.domains === 'string') {
+    if (typeof normalized.domainLocation !== 'string' || !normalized.domainLocation.trim()) {
+      normalized.domainLocation = normalized.domains;
+    }
+    delete normalized.domains;
+    warnings.push({
+      code: 'deprecated-domains-string',
+      severity: 'warning',
+      message: 'host projectDocs.domains as a string is deprecated; use domainLocation for the zone path and domains as the ID-prefix array'
+    });
+  }
+  return { projectDocs: normalized, warnings };
+}
+
 function projectDocsConfigPath(workspaceRoot) {
   return path.join(workspaceRoot, PROJECT_DOCS_CONFIG);
 }
@@ -148,22 +167,12 @@ function inspectHostProjectDocs(workspaceRoot) {
       continue;
     }
 
-    const projectDocs = { ...manifest.projectDocs };
-    if (typeof projectDocs.domains === 'string') {
-      if (typeof projectDocs.domainLocation !== 'string' || !projectDocs.domainLocation.trim()) {
-        projectDocs.domainLocation = projectDocs.domains;
-      }
-      delete projectDocs.domains;
-      entry.warnings.push({
-        code: 'deprecated-domains-string',
-        severity: 'warning',
-        path: configSource(workspaceRoot, file),
-        message: 'host projectDocs.domains as a string is deprecated; use domainLocation for the zone path and domains as the ID-prefix array'
-      });
-    }
+    const normalizedHost = normalizeHostProjectDocs(manifest.projectDocs);
+    const projectDocs = normalizedHost.projectDocs;
 
     const validation = validateDocsConfig(projectDocs);
     const source = configSource(workspaceRoot, file);
+    entry.warnings.push(...normalizedHost.warnings.map(item => ({ ...item, path: source })));
     entry.warnings.push(...validation.warnings.map(item => ({ ...item, path: source })));
     if (!validation.valid) {
       const details = validation.diagnostics.map(item => item.message).join('; ');
@@ -236,6 +245,13 @@ function validateDocsConfig(config) {
     return { valid: false, diagnostics, warnings };
   }
 
+  for (const field of ['docLocation', 'tracker', 'issueDefinition']) {
+    if (config[field] !== undefined && typeof config[field] !== 'string') {
+      const diagnosticField = field.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+      invalid(`invalid-${diagnosticField}-type`, `${field} must be a string when provided`);
+    }
+  }
+
   for (const key of Object.keys(config).sort()) {
     if (!PROJECT_DOC_CONFIG_KEYS.has(key)) {
       warnings.push({
@@ -754,6 +770,7 @@ module.exports = {
   readProjectDocs,
   resolveDocsConfig,
   validateDocsConfig,
+  normalizeHostProjectDocs,
   parseContextMap,
   resolveProjectDocs,
   detectProjectDocsConventions,