@indigoai-us/hq-cli 5.345.142 → 5.345.144

package/dist/commands/core-policy.js

@@ -4,6 +4,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { policyValidatorDiagnostic } from '../lib/policy-validator.js';
+import { evaluateTrigger } from '../utils/core-eval-trigger.js';
 import { packageRoot, resolveLiveRoot } from '../utils/hq-roots.js';
 import { describeCoreCommand } from './core-command-catalog.js';
 import { runPolicyFrontmatter as runPolicyFrontmatterImpl } from './core-policy-frontmatter.js';
@@ -165,12 +166,46 @@ function frontmatterScalar(file, key) {
             value = value.replace(/^["']|["']$/g, '');
         if (key === 'source' || key === 'created')
             value = value.replaceAll('"', '');
-        if (key === 'created')
+        if (key === 'updated')
+            value = value.replace(/^["']|["']$/g, '');
+        if (key === 'created' || key === 'updated')
             return value.slice(0, 10);
         return value;
     }
     return '';
 }
+/**
+ * The `when:` expression as inject-policy-on-trigger.sh reads it: the last
+ * `when:` line in the frontmatter, trailing ` # comment` removed, surrounding
+ * quotes stripped. Returns the expression when the canonical trigger evaluator
+ * (the one behind eval-trigger.sh) rejects it as malformed, so the policy can
+ * never match an event; undefined when it parses or there is no `when:`.
+ */
+function malformedTrigger(text) {
+    const lines = text.split('\n');
+    if (!(lines[0] ?? '').startsWith('---'))
+        return undefined;
+    let depth = 0;
+    let when;
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\r$/, '');
+        if (/^---[ \t]*$/.test(line)) {
+            depth += 1;
+            if (depth === 2)
+                break;
+            continue;
+        }
+        if (depth !== 1 || !line.startsWith('when:'))
+            continue;
+        when = line
+            .replace(/^when:[ \t]*/, '')
+            .replace(/[ \t]+#.*$/, '')
+            .replace(/^["']|["']$/g, '');
+    }
+    if (when === undefined || when.trim() === '')
+        return undefined;
+    return evaluateTrigger(when, '') === 2 ? when : undefined;
+}
 function ruleBody(file) {
     const text = fileText(file) ?? '';
     const lines = text.split('\n');
@@ -438,8 +473,18 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
             const enforcement = frontmatterScalar(file, 'enforcement') || 'unset';
             const source = frontmatterScalar(file, 'source');
             const version = frontmatterScalar(file, 'version');
-            const createdEpoch = epochFromDate(frontmatterScalar(file, 'created')) || statMtimeSeconds(file) || 0;
+            const mtimeEpoch = statMtimeSeconds(file);
+            const createdEpoch = epochFromDate(frontmatterScalar(file, 'created')) || mtimeEpoch || 0;
             const ageDays = Math.trunc((now - createdEpoch) / 86400);
+            // Usage history counts only from the last change to the policy (and so
+            // to its trigger): `updated:` frontmatter or the file mtime, whichever is
+            // newer. A trigger that was malformed and was just repaired is not judged
+            // on the period when it could not fire. An mtime later than the report
+            // clock (pinned clock or clock skew) is not a usable change date.
+            const changedEpoch = mtimeEpoch !== undefined && mtimeEpoch <= now ? mtimeEpoch : 0;
+            const clockEpoch = Math.max(createdEpoch, epochFromDate(frontmatterScalar(file, 'updated')), changedEpoch);
+            const clockDays = Math.trunc((now - clockEpoch) / 86400);
+            const brokenTrigger = malformedTrigger(text);
             const fired = usage.counts.get(id) ?? 0;
             const lastEpoch = usage.newest.get(id);
             const lastFired = lastEpoch === undefined ? null : new Date(lastEpoch * 1000).toISOString().slice(0, 10);
@@ -448,24 +493,30 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
             const refs = refSummary(file, root);
             const singleIncident = ['user-correction', 'session-learning', 'back-pressure-failure'].includes(source) && (version || '1') === '1';
             const classes = [];
-            if (fired === 0) {
-                const comparison = bashTestGreaterOrEqual(ageDays, parsed.minAge, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 173, platform);
+            if (brokenTrigger !== undefined) {
+                // A policy whose `when:` cannot parse never had a chance to fire, so
+                // its usage history says nothing about whether the rule is needed. It
+                // is reported as broken and never offered for retirement.
+                classes.push('malformed-trigger');
+            }
+            else if (fired === 0) {
+                const comparison = bashTestGreaterOrEqual(clockDays, parsed.minAge, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 173, platform);
                 stderr += comparison.stderr;
                 if (comparison.value && usage.anyFiles)
                     classes.push('never-fired');
             }
-            if (fired > 0) {
-                const comparison = bashTestGreaterOrEqual(lastAge, parsed.dormantDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 174, platform);
+            if (brokenTrigger === undefined && fired > 0) {
+                const comparison = bashTestGreaterOrEqual(Math.min(lastAge, clockDays), parsed.dormantDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 174, platform);
                 stderr += comparison.stderr;
                 if (comparison.value)
                     classes.push('dormant');
             }
-            if (refs.stale.length > 0)
+            if (brokenTrigger === undefined && refs.stale.length > 0)
                 classes.push('stale-refs');
-            if (refs.renamed.length > 0)
+            if (brokenTrigger === undefined && refs.renamed.length > 0)
                 classes.push('renamed-refs');
-            if (singleIncident) {
-                const comparison = bashTestGreaterOrEqual(ageDays, parsed.incidentDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 178, platform);
+            if (brokenTrigger === undefined && singleIncident) {
+                const comparison = bashTestGreaterOrEqual(clockDays, parsed.incidentDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 178, platform);
                 stderr += comparison.stderr;
                 if (comparison.value && fired <= 1)
                     classes.push('single-incident-old');
@@ -484,6 +535,7 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
                 retrieved,
                 refs_judged: refs.judged,
                 renamed_refs: refs.renamed,
+                ...(brokenTrigger === undefined ? {} : { malformed_trigger: brokenTrigger }),
             });
         }
     }
@@ -491,10 +543,14 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
         const selected = parsed.candidates ? rows.filter((row) => row.candidate_classes.length > 0) : rows;
         return policyResult(0, `${JSON.stringify(selected)}\n`, stderr);
     }
-    const never = rows.filter((row) => row.fired === 0).length;
-    const staleTotal = rows.filter((row) => row.stale_refs.length > 0).length;
-    const candidateCount = rows.filter((row) => row.candidate_classes.length > 0).length;
+    const malformed = rows.filter((row) => row.malformed_trigger !== undefined);
+    const never = rows.filter((row) => row.fired === 0 && row.malformed_trigger === undefined).length;
+    const staleTotal = rows.filter((row) => row.stale_refs.length > 0 && row.malformed_trigger === undefined).length;
+    const candidateCount = rows.filter((row) => row.candidate_classes.length > 0 && row.malformed_trigger === undefined).length;
     let stdout = `policy-age-report: ${rows.length} policies, ${never} never fired, ${staleTotal} with stale references, ${candidateCount} retirement candidates (min-age ${parsed.minAge}d, dormant ${parsed.dormantDays}d, incident ${parsed.incidentDays}d)\n`;
+    if (malformed.length > 0) {
+        stdout += `policy-age-report: ${malformed.length} with a malformed when: trigger that cannot fire (fix the trigger; not retirement candidates): ${malformed.map((row) => row.id).sort().join(', ')}\n`;
+    }
     if (!parsed.candidates)
         stdout += '  (add --candidates to list them, --json for machine-readable rows)\n';
     else {
@@ -805,6 +861,13 @@ function autoRetire(options, root, cwd, env, now) {
                 continue;
         }
         let why = '';
+        if (classes.split(',').includes('malformed-trigger')) {
+            const expression = candidate.malformed_trigger ?? '';
+            reportText += `- needs-fix (not retired) **${candidate.id}** (${candidate.path}): malformed when: trigger, so it can never fire: ${expression}\n`;
+            stderr += `policy-retire: ${candidate.id} (${candidate.path}) has a malformed when: trigger and was not retired; fix it: ${expression}\n`;
+            needfix += 1;
+            continue;
+        }
         if (classes.split(',').includes('renamed-refs')) {
             reportText += `- needs-fix (not retired) **${candidate.id}** (${candidate.path}): referenced file was renamed: ${candidate.renamed_refs.join(', ')}\n`;
             needfix += 1;

package/dist/commands/library-add.d.ts

@@ -0,0 +1,120 @@
+import { Readable } from "node:stream";
+import { type CloudAssetMediaKind } from "@indigoai-us/hq-cloud";
+import type { LibraryCaptionNote, LibraryCaptionRequest } from "./library-caption.js";
+export interface LibraryCompany {
+    uid: string;
+    slug: string;
+}
+export interface LibrarySource {
+    kind: "file" | "url";
+    /** The argument as given. */
+    input: string;
+    /** File name the placeholder is written under. */
+    name: string;
+}
+export interface OpenedSource {
+    stream: Readable;
+    contentType?: string;
+}
+export interface PutResponse {
+    status: number;
+    headers: Record<string, string | undefined>;
+}
+export interface LibraryAddDeps {
+    hqRoot: string;
+    now: () => Date;
+    /** Resolve the slug to an active company membership. */
+    resolveCompany: (slug: string) => Promise<LibraryCompany>;
+    /** POST /v1/files/presign. */
+    presign: (body: Record<string, unknown>) => Promise<Response>;
+    /** Open a fresh byte stream of a source. Called once to hash and once to upload. */
+    openSource: (source: LibrarySource) => Promise<OpenedSource>;
+    /** PUT `body` (exactly `size` bytes) to a presigned URL with `headers`. */
+    put: (url: string, headers: Record<string, string>, body: Readable, size: number) => Promise<PutResponse>;
+    writePlaceholder: (file: string, text: string) => Promise<void>;
+    /**
+     * Caption one written image or video placeholder (US-006). Must not throw:
+     * a caption failure never fails the upload. Absent = no captioning.
+     */
+    caption?: (request: LibraryCaptionRequest) => Promise<LibraryCaptionNote>;
+}
+export interface LibraryAddOptions {
+    company?: string;
+    to?: string;
+    tags: string[];
+    title?: string;
+    note?: string;
+}
+export interface LibraryAddItem {
+    source: string;
+    ok: boolean;
+    /** HQ-relative placeholder path (set when written). */
+    placeholderPath?: string;
+    originalPath?: string;
+    key?: string;
+    size?: number;
+    sha256?: string;
+    /** False when the vault already held the bytes. */
+    uploaded?: boolean;
+    error?: string;
+    /** AI caption outcome, set when captioning ran for this item. */
+    caption?: LibraryCaptionNote;
+}
+export interface LibraryAddResult {
+    company: string;
+    items: LibraryAddItem[];
+}
+export declare function contentTypeFor(name: string, served?: string): string;
+export declare function mediaKindFor(contentType: string): CloudAssetMediaKind;
+/** A file name safe to place in one directory: no separators, no control chars. */
+export declare function safeAssetName(raw: string): string;
+/** Classify an argument: an http(s) URL, otherwise a local file. */
+export declare function parseSource(input: string): LibrarySource;
+/**
+ * The library directory, HQ-relative. `--to` resolves against the HQ root and
+ * must be inside `companies/<co>/`, so `hq storage fetch` can find the
+ * company vault from the placeholder path. The default is
+ * `companies/<co>/library`.
+ */
+export declare function resolveLibraryDir(hqRoot: string, options: Pick<LibraryAddOptions, "company" | "to">): {
+    slug: string;
+    dirRel: string;
+    dirAbs: string;
+};
+export declare function offloadTimestamp(now: Date): string;
+/**
+ * Testable core. Every source is hashed first, then one presign request
+ * covers all of them (hq-pro rate-limits presign per user). A 402 for the
+ * request refuses every source and writes nothing; a per-key refusal fails
+ * only that source.
+ */
+export declare function runLibraryAdd(inputs: readonly string[], options: LibraryAddOptions, deps: LibraryAddDeps): Promise<LibraryAddResult>;
+export interface LibraryTagResult {
+    placeholderPath: string;
+    tags: string[];
+    changed: boolean;
+}
+/**
+ * Add and remove tags on a library placeholder. The placeholder is parsed and
+ * re-rendered by hq-cloud's placeholder writer, then replaced atomically
+ * (temp file + rename), so a sync watcher never reads a half-written file.
+ */
+export declare function runLibraryTag(hqRoot: string, target: string, edits: {
+    add: string[];
+    remove: string[];
+}, now?: () => Date): Promise<LibraryTagResult>;
+/** Replace a placeholder atomically (temp file + rename). */
+export declare function replacePlaceholderText(file: string, text: string): Promise<void>;
+/** Open a local file or GET a URL as a Node stream. */
+export declare function openLibrarySource(source: LibrarySource): Promise<OpenedSource>;
+/**
+ * Stream a PUT with an explicit Content-Length: S3 presigned PUTs refuse
+ * chunked transfer encoding, which fetch would use for a stream body.
+ */
+export declare function streamPut(url: string, headers: Record<string, string>, body: Readable, size: number): Promise<PutResponse>;
+export declare const defaultLibraryIo: {
+    openSource: typeof openLibrarySource;
+    put: typeof streamPut;
+    writePlaceholder: (file: string, text: string) => Promise<void>;
+};
+//# sourceMappingURL=library-add.d.ts.map