agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/registries/artifactProtocolIds.js

@@ -0,0 +1,78 @@
+/**
+ * Decision 58 artifact protocol names: one `artifact_id` per artifact in CLI,
+ * hooks, validators, and JSON envelopes. Storage paths live here only.
+ */
+export const ARTIFACT_PROTOCOL_PATHS = {
+    vision: ".agentera/vision.yaml",
+    decisions: ".agentera/decisions.yaml",
+    plan: ".agentera/plan.yaml",
+    progress: ".agentera/progress.yaml",
+    health: ".agentera/health.yaml",
+    docs: ".agentera/docs.yaml",
+    objective: ".agentera/objective.yaml",
+    experiments: ".agentera/experiments.yaml",
+    todo: "TODO.md",
+    changelog: "CHANGELOG.md",
+    design: "DESIGN.md",
+    glossary: ".agentera/glossary.yaml",
+};
+export const HUMAN_FACING_ARTIFACT_IDS = new Set(["todo", "changelog", "design"]);
+export const TRACKED_ARTIFACT_IDS = [
+    "progress",
+    "decisions",
+    "plan",
+    "health",
+    "design",
+    "docs",
+    "vision",
+    "todo",
+    "changelog",
+];
+export const VALIDATE_ARTIFACT_PROTOCOL_IDS = [
+    "changelog",
+    "decisions",
+    "design",
+    "docs",
+    "health",
+    "plan",
+    "progress",
+    "todo",
+    "vision",
+    "glossary",
+];
+function artifactProtocolStem(input) {
+    const lower = input.trim().toLowerCase();
+    return lower.endsWith(".md") ? lower.slice(0, -3) : lower;
+}
+export function normalizeArtifactProtocolId(input) {
+    const trimmed = input.trim();
+    if (trimmed in ARTIFACT_PROTOCOL_PATHS) {
+        return trimmed;
+    }
+    const lower = trimmed.toLowerCase();
+    if (lower in ARTIFACT_PROTOCOL_PATHS) {
+        return lower;
+    }
+    const stem = artifactProtocolStem(trimmed);
+    if (stem in ARTIFACT_PROTOCOL_PATHS) {
+        return stem;
+    }
+    return null;
+}
+export function requireArtifactProtocolId(input, context) {
+    const id = normalizeArtifactProtocolId(input);
+    if (id === null) {
+        const valid = VALIDATE_ARTIFACT_PROTOCOL_IDS.join(", ");
+        throw new Error(`unsupported artifact ${JSON.stringify(input)} in ${context}; valid artifact_id values: ${valid}`);
+    }
+    return id;
+}
+/** Normalize docs.yaml mapping keys to artifact_id. */
+export function normalizeArtifactMappingKeys(mapping) {
+    const out = {};
+    for (const [key, value] of Object.entries(mapping)) {
+        const id = normalizeArtifactProtocolId(key);
+        out[id ?? key] = value;
+    }
+    return out;
+}

package/dist/registries/artifactRegistry.js

@@ -2,9 +2,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { loadYamlMapping } from "../core/yaml.js";
+import { resolveProfileDirOverride } from "../core/envPaths.js";
 import { resolvePath } from "../core/paths.js";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
 import { resolveCandidate } from "../state/installRoot.js";
+import { ARTIFACT_PROTOCOL_PATHS } from "./artifactProtocolIds.js";
 function sourceRoot() {
     return resolveSourceRoot();
 }
@@ -36,12 +38,11 @@ export function normalizePath(p) {
     s = s.replace(/<objective-name>/g, "<name>");
     return s.trim();
 }
-const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
 const URI_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:/;
 const ENCODED_TRAVERSAL_RE = /%(?:2e|2f|5c)/i;
 const WINDOWS_DRIVE_RE = /^[A-Za-z]:[\\/]/;
 function rejectUnsafeArtifactPath(p, artifactId) {
-    if (CONTROL_CHAR_RE.test(p)) {
+    if ([...p].some((char) => char.charCodeAt(0) <= 31 || char.charCodeAt(0) === 127)) {
         throw new Error(`artifact '${artifactId}' path contains control characters`);
     }
     if (ENCODED_TRAVERSAL_RE.test(p)) {
@@ -67,28 +68,141 @@ function projectPath(projectRoot, artifactPath, artifactId) {
     }
     return resolved;
 }
-function schemaMetas(dir) {
-    const metas = new Map();
+export const EXPECTED_ARTIFACT_SCHEMA_VERSION = "1.0.0";
+function readSchemaMeta(file) {
+    const meta = loadYaml(file).meta;
+    if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+        return null;
+    }
+    return meta;
+}
+function warnMalformedSchemaMeta(name) {
+    process.stderr.write(`warning: artifact schema ${name} is missing meta; expected v3 schema version ${EXPECTED_ARTIFACT_SCHEMA_VERSION}\n`);
+}
+function warnSchemaVersionMismatch(meta, name) {
+    const version = String(meta.version ?? "").trim();
+    if (!version || version !== EXPECTED_ARTIFACT_SCHEMA_VERSION) {
+        const reported = version || "(missing)";
+        process.stderr.write(`warning: artifact schema ${name} version ${reported} does not match expected v3 schema version ${EXPECTED_ARTIFACT_SCHEMA_VERSION}\n`);
+    }
+}
+function listSchemaFiles(dir) {
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
-        return metas;
+        return [];
     }
-    const files = fs
+    return fs
         .readdirSync(dir)
         .filter((name) => name.endsWith(".yaml"))
         .sort();
-    for (const name of files) {
-        const meta = loadYaml(path.join(dir, name)).meta;
-        if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+}
+/**
+ * Full schema-meta index over an artifact schemas directory. Emits malformed-meta
+ * and version-mismatch warnings for every schema file; the full loader relies on
+ * this strict coverage to surface drift across the whole identity set.
+ */
+function schemaMetas(dir) {
+    const metas = new Map();
+    for (const name of listSchemaFiles(dir)) {
+        const meta = readSchemaMeta(path.join(dir, name));
+        if (!meta) {
+            warnMalformedSchemaMeta(name);
             continue;
         }
-        const m = meta;
-        const artifactId = String(m.name ?? "").trim();
+        warnSchemaVersionMismatch(meta, name);
+        const artifactId = String(meta.name ?? "").trim();
         if (artifactId) {
-            metas.set(artifactId, m);
+            metas.set(artifactId, meta);
         }
     }
     return metas;
 }
+/**
+ * Targeted schema-meta lookup for a single artifact identity. Walks the schemas
+ * directory only to find the file whose `meta.name` matches `artifactId`, and
+ * emits warnings only for that schema. Unrelated malformed or version-mismatched
+ * schemas in the same directory stay silent so callers resolving a single
+ * identity (e.g. `profile`) don't fan out noise across the required-identity set.
+ */
+function loadSchemaMetaForArtifact(dir, artifactId) {
+    for (const name of listSchemaFiles(dir)) {
+        let meta;
+        try {
+            meta = readSchemaMeta(path.join(dir, name));
+        }
+        catch {
+            continue;
+        }
+        if (!meta)
+            continue;
+        if (String(meta.name ?? "").trim() !== artifactId)
+            continue;
+        warnSchemaVersionMismatch(meta, name);
+        return meta;
+    }
+    return null;
+}
+function findRequiredIdentity(model, artifactId) {
+    const identities = (model.required_artifact_identities ?? {});
+    for (const [scope, identityList] of Object.entries(identities)) {
+        if (!Array.isArray(identityList))
+            continue;
+        for (const identity of identityList) {
+            if (!identity || typeof identity !== "object" || Array.isArray(identity))
+                continue;
+            const id = identity;
+            if (String(id.artifact_id ?? "").trim() === artifactId) {
+                return { scope, identity: id };
+            }
+        }
+    }
+    return null;
+}
+function findSpecialCase(model, artifactId) {
+    const specialCases = (model.explicit_special_cases ?? []);
+    for (const special of specialCases) {
+        if (!special || typeof special !== "object" || Array.isArray(special))
+            continue;
+        const sp = special;
+        if (String(sp.artifact_id ?? "").trim() === artifactId) {
+            return sp;
+        }
+    }
+    return null;
+}
+function buildRequiredRecord(scope, identity, meta) {
+    const template = identity.path_template;
+    return {
+        artifactId: String(identity.artifact_id ?? "").trim(),
+        displayName: String(identity.display_name ?? "").trim(),
+        defaultPath: normalizePath(String(identity.default_path ?? meta.path ?? "")),
+        producers: asSet(meta.producer),
+        consumers: asSet(meta.consumers),
+        artifactType: String(meta.artifact_type ?? "").trim(),
+        scope: String(scope),
+        pathTemplate: template && typeof template === "object" && !Array.isArray(template)
+            ? template
+            : null,
+        docsYamlCanOverridePath: true,
+        implementationStatus: String(meta.implementation_status ?? "implemented").trim(),
+    };
+}
+function buildSpecialCaseRecord(sp) {
+    const template = sp.path_template;
+    return {
+        artifactId: String(sp.artifact_id ?? "").trim(),
+        displayName: String(sp.display_name ?? "").trim(),
+        defaultPath: normalizePath(String(sp.default_path ?? "")),
+        producers: asSet(sp.producers),
+        consumers: asSet(sp.consumers),
+        artifactType: String(sp.artifact_type ?? "").trim(),
+        scope: String(sp.scope ?? "").trim(),
+        pathTemplate: template && typeof template === "object" && !Array.isArray(template)
+            ? template
+            : null,
+        docsYamlCanOverridePath: Boolean(sp.docs_yaml_can_override_path),
+        implementationStatus: String(sp.implementation_status ?? "implemented").trim(),
+    };
+}
 export function loadArtifactRegistry(artifactSchemasDirPath = artifactSchemasDir(), registryModelPathArg = registryModelPath()) {
     const model = loadYaml(registryModelPathArg);
     const metas = schemaMetas(artifactSchemasDirPath);
@@ -104,24 +218,15 @@ export function loadArtifactRegistry(artifactSchemasDirPath = artifactSchemasDir
             }
             const id = identity;
             const artifactId = String(id.artifact_id ?? "").trim();
+            if (!artifactId) {
+                continue;
+            }
             const meta = metas.get(artifactId);
-            if (!artifactId || !meta) {
+            if (!meta) {
+                process.stderr.write(`warning: required artifact identity '${artifactId}' has no matching schema file in ${artifactSchemasDirPath}\n`);
                 continue;
             }
-            const template = id.path_template;
-            records.set(artifactId, {
-                artifactId,
-                displayName: String(id.display_name ?? "").trim(),
-                defaultPath: normalizePath(String(id.default_path ?? meta.path ?? "")),
-                producers: asSet(meta.producer),
-                consumers: asSet(meta.consumers),
-                artifactType: String(meta.artifact_type ?? "").trim(),
-                scope: String(scope),
-                pathTemplate: template && typeof template === "object" && !Array.isArray(template)
-                    ? template
-                    : null,
-                docsYamlCanOverridePath: true,
-            });
+            records.set(artifactId, buildRequiredRecord(scope, id, meta));
         }
     }
     const specialCases = (model.explicit_special_cases ?? []);
@@ -134,73 +239,129 @@ export function loadArtifactRegistry(artifactSchemasDirPath = artifactSchemasDir
         if (!artifactId) {
             continue;
         }
-        const template = sp.path_template;
-        records.set(artifactId, {
-            artifactId,
-            displayName: String(sp.display_name ?? "").trim(),
-            defaultPath: normalizePath(String(sp.default_path ?? "")),
-            producers: asSet(sp.producers),
-            consumers: asSet(sp.consumers),
-            artifactType: String(sp.artifact_type ?? "").trim(),
-            scope: String(sp.scope ?? "").trim(),
-            pathTemplate: template && typeof template === "object" && !Array.isArray(template)
-                ? template
-                : null,
-            docsYamlCanOverridePath: Boolean(sp.docs_yaml_can_override_path),
-        });
+        records.set(artifactId, buildSpecialCaseRecord(sp));
     }
     return records;
 }
-export function loadDocsPathOverrides(projectRoot) {
-    const docsPath = path.join(projectRoot, ".agentera", "docs.yaml");
-    if (!fs.existsSync(docsPath)) {
-        return {};
+/**
+ * Targeted lookup of a single artifact record. Resolves against the same
+ * model/schema authority as `loadArtifactRegistry` but inspects only the
+ * requested identity, so a special case such as `profile` loads without
+ * walking or warning about unrelated required schemas. A requested required
+ * identity still warns and returns `undefined` when its matching schema file is
+ * missing from the schemas directory.
+ */
+export function loadArtifactRecord(artifactId, artifactSchemasDirPath = artifactSchemasDir(), registryModelPathArg = registryModelPath()) {
+    const model = loadYaml(registryModelPathArg);
+    const specialCase = findSpecialCase(model, artifactId);
+    if (specialCase) {
+        return buildSpecialCaseRecord(specialCase);
+    }
+    const required = findRequiredIdentity(model, artifactId);
+    if (!required) {
+        return undefined;
     }
+    const meta = loadSchemaMetaForArtifact(artifactSchemasDirPath, artifactId);
+    if (!meta) {
+        process.stderr.write(`warning: required artifact identity '${artifactId}' has no matching schema file in ${artifactSchemasDirPath}\n`);
+        return undefined;
+    }
+    return buildRequiredRecord(required.scope, required.identity, meta);
+}
+export function docsPathOverridesFromBytes(bytes, strict = false) {
     let data;
     try {
-        data = loadYamlMapping(fs.readFileSync(docsPath, "utf8"));
+        data = loadYamlMapping(bytes.toString());
     }
     catch (exc) {
+        if (strict)
+            throw new Error(`failed to load docs path overrides: ${exc.message}`);
         process.stderr.write(`warning: failed to load docs path overrides: ${exc.message}\n`);
         return {};
     }
     const mapping = data.mapping;
     if (!Array.isArray(mapping)) {
+        if (strict && mapping !== undefined)
+            throw new Error("failed to load docs path overrides: mapping must be a list");
         return {};
     }
     const overrides = {};
     for (const entry of mapping) {
         if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            if (strict)
+                throw new Error("failed to load docs path overrides: every mapping entry must be a mapping");
             continue;
         }
         const e = entry;
-        const artifact = e.artifact;
-        const p = e.path;
-        if (typeof artifact === "string" && typeof p === "string") {
-            overrides[artifact] = p;
-        }
+        if (typeof e.artifact === "string" && typeof e.path === "string")
+            overrides[e.artifact] = e.path;
+        else if (strict)
+            throw new Error("failed to load docs path overrides: every mapping entry requires string artifact and path fields");
     }
     return overrides;
 }
-export function resolveArtifactPath(record, projectRoot, activeObjectiveName = null, env = process.env) {
+export function loadDocsPathOverrides(projectRoot, strict = false) {
+    const docsPath = path.join(projectRoot, ARTIFACT_PROTOCOL_PATHS.docs);
+    if (!fs.existsSync(docsPath)) {
+        return {};
+    }
+    let bytes;
+    try {
+        bytes = fs.readFileSync(docsPath);
+    }
+    catch (exc) {
+        if (strict)
+            throw new Error(`failed to load docs path overrides: ${exc.message}`);
+        process.stderr.write(`warning: failed to load docs path overrides: ${exc.message}\n`);
+        return {};
+    }
+    return docsPathOverridesFromBytes(bytes, strict);
+}
+function nearestExistingAncestor(p) {
+    let current = p;
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return fs.realpathSync.native(current);
+}
+export function assertRealpathBoundary(projectRoot, artifactPath, artifactId) {
+    const projectReal = nearestExistingAncestor(resolvePath(projectRoot));
+    const ancestorReal = nearestExistingAncestor(artifactPath);
+    const rel = path.relative(projectReal, ancestorReal);
+    if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) {
+        throw new Error(`artifact '${artifactId}' path escapes the project boundary`);
+    }
+}
+export function resolveArtifactPath(record, projectRoot, activeObjectiveNameOrOptions = null, env = process.env) {
+    const options = typeof activeObjectiveNameOrOptions === "object" && activeObjectiveNameOrOptions !== null
+        ? activeObjectiveNameOrOptions
+        : { activeObjectiveName: activeObjectiveNameOrOptions };
+    const activeObjectiveName = options.activeObjectiveName ?? null;
     let artifactPath = record.defaultPath;
-    const overrides = loadDocsPathOverrides(projectRoot);
+    const overrides = options.docsPathOverrides ?? loadDocsPathOverrides(projectRoot, options.strictWrite === true);
     if (record.docsYamlCanOverridePath && record.displayName in overrides) {
         artifactPath = overrides[record.displayName];
     }
     if (artifactPath.includes("<name>") && activeObjectiveName) {
         artifactPath = artifactPath.replace(/<name>/g, activeObjectiveName);
     }
-    const profilePrefix = "$PROFILERA_PROFILE_DIR/";
-    if (artifactPath.startsWith(profilePrefix)) {
-        const explicit = env.PROFILERA_PROFILE_DIR;
-        const suffix = artifactPath.slice(profilePrefix.length);
-        if (explicit) {
-            return path.join(explicit, suffix);
+    const profileDirPrefixes = ["$AGENTERA_PROFILE_DIR/", "$PROFILERA_PROFILE_DIR/"];
+    for (const prefix of profileDirPrefixes) {
+        if (artifactPath.startsWith(prefix)) {
+            const suffix = artifactPath.slice(prefix.length);
+            const explicit = resolveProfileDirOverride(env);
+            if (explicit) {
+                return path.join(explicit, suffix);
+            }
+            const [base] = resolveCandidate(null, { env, home: os.homedir() });
+            return path.join(base, suffix);
         }
-        const [base] = resolveCandidate(null, { env, home: os.homedir() });
-        return path.join(base, suffix);
     }
-    return projectPath(projectRoot, artifactPath, record.artifactId);
+    const resolved = projectPath(projectRoot, artifactPath, record.artifactId);
+    if (options.strictWrite)
+        assertRealpathBoundary(projectRoot, resolved, record.artifactId);
+    return resolved;
 }
-//# sourceMappingURL=artifactRegistry.js.map

package/dist/registries/artifactSchemaProjection.js

@@ -0,0 +1,45 @@
+const FIELD_SKIP = new Set([
+    "meta",
+    "GROUP_PREFIXES",
+    "BUDGET",
+    "COMPACTION",
+    "VALIDATION",
+    "ARCHIVE",
+    "CONVENTION",
+    "CONVENTIONS",
+]);
+function mapping(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+export function artifactSchemaFieldDescription(entry, group) {
+    return {
+        id: entry.id ?? null,
+        group,
+        field: entry.field ?? null,
+        ...(typeof entry.path === "string" ? { path: entry.path } : {}),
+        type: entry.type ?? "unknown",
+        required: "required" in entry ? entry.required : "unknown",
+        format: entry.format ?? null,
+        validation: entry.validation ?? [],
+        ...(entry.accepted_forms !== undefined ? { accepted_forms: structuredClone(entry.accepted_forms) } : {}),
+        ...(entry.normalization !== undefined ? { normalization: structuredClone(entry.normalization) } : {}),
+        ...(entry.write_operations !== undefined ? { write_operations: structuredClone(entry.write_operations) } : {}),
+    };
+}
+export function describeArtifactSchemaFields(schema) {
+    const fields = [];
+    for (const [group, value] of Object.entries(schema)) {
+        if (FIELD_SKIP.has(group) || !mapping(value))
+            continue;
+        for (const entry of Object.values(value)) {
+            if (mapping(entry) && "field" in entry)
+                fields.push(artifactSchemaFieldDescription(entry, group));
+        }
+    }
+    return fields;
+}
+export function artifactSchemaFieldsForOperation(schema, verb) {
+    if (!schema)
+        return [];
+    return describeArtifactSchemaFields(schema).filter((field) => Array.isArray(field.write_operations) && field.write_operations.includes(verb));
+}