@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/policy-validator.js

@@ -0,0 +1,187 @@
+const VALIDATION_NOTE = '\n(The HQ_ALLOW_POLICY_NO_TRIGGER override requires explicit human permission.\nAn agent must never set, export, or write it on its own initiative.)\n';
+function isPolicyPath(file) {
+    const low = file.toLowerCase().replaceAll('\\', '/');
+    const basename = low.slice(low.lastIndexOf('/') + 1);
+    return low.endsWith('.md')
+        && (low.includes('/policies/') || low.startsWith('policies/'))
+        && basename !== 'readme.md'
+        && !low.includes('/audit/');
+}
+function normalizeValidatorText(content) {
+    return content.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+}
+function hasValidTriggerGrammar(expression) {
+    let input = expression.replace(/[A-Za-z0-9_./][A-Za-z0-9_./-]*/g, '0');
+    if (/[^01&|!() \t]/.test(input))
+        return false;
+    let position = 0;
+    let valid = true;
+    const skip = () => { while (input[position] === ' ' || input[position] === '\t')
+        position += 1; };
+    let parseOr;
+    let parseAnd;
+    let parseNot;
+    let parseAtom;
+    parseAtom = () => {
+        skip();
+        const current = input[position];
+        if (current === '(') {
+            position += 1;
+            const result = parseOr();
+            skip();
+            if (input[position] !== ')') {
+                valid = false;
+                return false;
+            }
+            position += 1;
+            return result;
+        }
+        if (current === '0' || current === '1') {
+            position += 1;
+            return current === '1';
+        }
+        valid = false;
+        return false;
+    };
+    parseNot = () => {
+        skip();
+        if (input[position] === '!') {
+            position += 1;
+            return !parseNot();
+        }
+        return parseAtom();
+    };
+    parseAnd = () => {
+        let result = parseNot();
+        skip();
+        while (valid && input.slice(position, position + 2) === '&&') {
+            position += 2;
+            const rhs = parseNot();
+            result = result && rhs;
+            skip();
+        }
+        return result;
+    };
+    parseOr = () => {
+        let result = parseAnd();
+        skip();
+        while (valid && input.slice(position, position + 2) === '||') {
+            position += 2;
+            const rhs = parseAnd();
+            result = result || rhs;
+            skip();
+        }
+        return result;
+    };
+    input = input.replace(/\r/g, '');
+    if (input.replace(/[ \t]/g, '') === '')
+        return false;
+    parseOr();
+    skip();
+    return valid && position === input.length;
+}
+const MISSING_TRIGGER_HELP = `Every policy under */policies/ must declare BOTH:
+  when: <expression>   # e.g.  always  |  git && push  |  deploy || share
+  on:   [<events>]     # any of PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent, SessionStart
+These drive just-in-time policy injection. See
+core/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").
+Add both fields to the frontmatter, then retry.
+${VALIDATION_NOTE}`;
+function inspectPolicyTriggerFrontmatter(content) {
+    const normalized = normalizeValidatorText(content);
+    const match = /^\s*---[ \t]*\n([\s\S]*?)\n---[ \t]*(\n|$)/.exec(normalized);
+    if (!match) {
+        return {
+            diagnostic: `BLOCKED: policy file is missing required trigger frontmatter (missing: no-frontmatter).\n\n${MISSING_TRIGGER_HELP}`,
+        };
+    }
+    const frontmatter = match[1];
+    const whenLines = [...frontmatter.matchAll(/^[ \t]*when:[ \t]*(.*)$/gm)].map((entry) => entry[1] ?? '');
+    const hasWhen = whenLines.some((line) => /\S/.test(line));
+    const onMatch = /^[ \t]*on:[ \t]*\S/m.test(frontmatter);
+    const missing = [];
+    if (!hasWhen)
+        missing.push('when');
+    if (!onMatch)
+        missing.push('on');
+    if (missing.length > 0) {
+        return {
+            diagnostic: `BLOCKED: policy file is missing required trigger frontmatter (missing: ${missing.join(',')}).\n\n${MISSING_TRIGGER_HELP}`,
+            whenLines,
+        };
+    }
+    return { parsed: { normalized, match, frontmatter, whenLines }, whenLines };
+}
+function malformedTriggerDiagnostic(whenLines) {
+    let malformedWhen;
+    for (const when of whenLines) {
+        if (!hasValidTriggerGrammar(when))
+            malformedWhen = when;
+    }
+    if (malformedWhen === undefined)
+        return undefined;
+    const when = malformedWhen;
+    return `BLOCKED: policy file has a malformed when: trigger expression:\n\n  when: ${when}\n\nThe canonical trigger evaluator rejected it. A space is NOT an AND, and quoted\nphrases are NOT tokens. Use explicit boolean operators instead:\n  "pull request"  -> (pull && request)\n  "force-push"    -> force-push\n\nUse only identifiers joined by the documented boolean grammar:\n  when: <identifier>                 # e.g.  always  |  git  |  /deep-plan\n  when: <expr> && <expr>             # AND\n  when: <expr> || <expr>             # OR\n  when: ! <expr>                     # NOT\n  when: ( <expr> )                   # grouping\nIdentifiers may contain letters, digits, _, ., /, and internal -. Quotes,\nYAML block scalars, adjacent identifiers without an operator, and other\npunctuation are not valid. See core/knowledge/public/hq-core/policies-spec.md\n("Trigger Expressions"). Fix the expression, then retry.\n${VALIDATION_NOTE}`;
+}
+/**
+ * Load-time validation: reject policy files that cannot participate in the
+ * trigger system. Authoring-only hard-policy constraints remain in the hook.
+ */
+export function policyLoadDiagnostic(content, filePath) {
+    if (!isPolicyPath(filePath))
+        return undefined;
+    // Partial frontmatter (for example `when:` without `on:`) still has its
+    // `when:` grammar checked, so a malformed expression is never loaded.
+    const { whenLines } = inspectPolicyTriggerFrontmatter(content);
+    if (!whenLines)
+        return undefined;
+    return malformedTriggerDiagnostic(whenLines);
+}
+export function policyValidatorDiagnostic(content, filePath, env) {
+    if (!isPolicyPath(filePath))
+        return undefined;
+    const inspected = inspectPolicyTriggerFrontmatter(content);
+    if (inspected.diagnostic)
+        return inspected.diagnostic;
+    const { normalized, match, frontmatter, whenLines } = inspected.parsed;
+    const enforcement = /^[ \t]*enforcement:[ \t]*["']?([A-Za-z]+)["']?/m.exec(frontmatter)?.[1]?.toLowerCase();
+    if (enforcement === 'hard') {
+        const tautological = whenLines.some((line) => !/[&!]/.test(line.toLowerCase()) && /(^|[^A-Za-z0-9_./-])always([^A-Za-z0-9_./-]|$)/i.test(line));
+        const onLine = /^[ \t]*on:[ \t]*(.*)$/m.exec(frontmatter)?.[1] ?? '';
+        const reactive = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'AssistantIntent'].filter((event) => onLine.includes(event));
+        if (tautological && reactive.length > 0) {
+            const events = reactive.join(', ');
+            return `BLOCKED: an enforcement: hard policy pairs an unconditional \`when:\` with a
+reactive event (${events}).
+
+\`when: always\` is TRUE for every command, prompt, and message. On a reactive
+event the injector ranks that as an event-specific match, so it takes the
+session cap slot of a policy that genuinely matched the thing you are doing —
+the loose trigger crowds out the precise one.
+
+Pick one:
+  when: always          + on: [SessionStart]        # ambient governance rule
+  when: <real signal>   + on: [PreToolUse, ...]     # e.g. deploy || publish
+
+Name the word(s) that actually appear when the rule is relevant. See
+core/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").
+${VALIDATION_NOTE}`;
+        }
+        const after = normalized.slice(match.index + match[0].length);
+        const binding = [];
+        const stop = /^#+[ \t]*(rationale|rationale and context|background|change history|changelog|history|examples?|references?|related|see also|sources?|provenance|evidence)[ \t]*$/i;
+        for (const line of after.split('\n')) {
+            if (stop.test(line.trim().toLowerCase()))
+                break;
+            binding.push(line);
+        }
+        const byteCount = Buffer.byteLength(binding.join('\n').trim(), 'utf8');
+        const rawMax = env.HQ_POLICY_HARD_RULE_MAX_BYTES || '6144';
+        const max = Number.parseInt(rawMax, 10);
+        if (Number.isFinite(max) && max > 0 && byteCount > max) {
+            return `BLOCKED: enforcement: hard policy body is ${byteCount} bytes; the limit is ${rawMax}.\n\nA hard policy is injected VERBATIM into the session, so its length is a\nrecurring context cost for every session it fires in. Keep the binding rule\ntight and move the reasoning out of the injected span: everything from the\nfirst \`## Rationale\` / \`## Background\` / \`## Change history\` /\n\`## Examples\` / \`## References\` heading onward is NOT counted and NOT\ninjected, so long-form context belongs there.\n\nIf the rule genuinely needs more than that, either split it into separate\npolicies with distinct triggers, or raise HQ_POLICY_HARD_RULE_MAX_BYTES in\n.claude/settings.local.json "env".\n${VALIDATION_NOTE}`;
+        }
+    }
+    return malformedTriggerDiagnostic(whenLines);
+}
+//# sourceMappingURL=policy-validator.js.map

package/dist/lib/process-flag-company-context.d.ts

@@ -0,0 +1,8 @@
+/** Company scope shared by the full flag registry and its fast-path reader. */
+export interface ProcessFlagCompanyContext {
+    companyUid?: string;
+    companySlug?: string;
+}
+/** Resolve the same company identity the process-wide flag reader uses. */
+export declare function resolveProcessFlagCompanyContext(env?: NodeJS.ProcessEnv): ProcessFlagCompanyContext;
+//# sourceMappingURL=process-flag-company-context.d.ts.map

package/dist/lib/process-flag-company-context.js

@@ -0,0 +1,67 @@
+/** Company scope shared by the full flag registry and its fast-path reader. */
+import { readMachineCompanyBinding } from "./work-context/company.js";
+import { readSessionState } from "./work-context/state.js";
+import { workContextRoot } from "./work-context/paths.js";
+import { readCompaniesManifestMap } from "./work-context/repo-remote.js";
+import { resolveDefaultHqRoot } from "../utils/hq-root-resolver.js";
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function normalizedCompanyUid(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
+}
+function normalizedCompanySlug(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_SLUG_RE.test(candidate) ? candidate : undefined;
+}
+/** Resolve explicit, machine, or bound-session company scope without defaults. */
+function processCompanyContext(env = process.env) {
+    const explicitUid = normalizedCompanyUid(env.HQ_COMPANY_UID);
+    const explicitSlug = normalizedCompanySlug(env.HQ_COMPANY_SLUG);
+    if (explicitUid || explicitSlug) {
+        return { companyUid: explicitUid, companySlug: explicitSlug };
+    }
+    const machine = readMachineCompanyBinding(env);
+    const spawnValue = env.HQ_SPAWN_COMPANY?.trim();
+    const spawnSlug = normalizedCompanySlug(spawnValue);
+    const machineContext = spawnValue && COMPANY_UID_RE.test(spawnValue)
+        ? { companyUid: spawnValue }
+        : spawnSlug
+            ? { companySlug: spawnSlug }
+            : {
+                companyUid: normalizedCompanyUid(machine?.uid),
+                companySlug: normalizedCompanySlug(machine?.slug),
+            };
+    if (machineContext.companyUid || machineContext.companySlug)
+        return machineContext;
+    const sessionId = env.HQ_SESSION_ID?.trim();
+    if (!sessionId)
+        return {};
+    const session = readSessionState(sessionId, workContextRoot(undefined, env));
+    if (session?.contextStatus !== "bound" || session.companyConfidence === "device_default") {
+        return {};
+    }
+    return {
+        companyUid: normalizedCompanyUid(session.companyUid),
+        companySlug: normalizedCompanySlug(session.companySlug),
+    };
+}
+function companyUidForContext(context, env = process.env) {
+    if (context.companyUid)
+        return context.companyUid;
+    if (!context.companySlug)
+        return undefined;
+    const hqRoot = resolveDefaultHqRoot({ env });
+    const manifestUid = readCompaniesManifestMap(hqRoot)?.[context.companySlug]?.cloud_uid;
+    return typeof manifestUid === "string" ? normalizedCompanyUid(manifestUid) : undefined;
+}
+/** Resolve the same company identity the process-wide flag reader uses. */
+export function resolveProcessFlagCompanyContext(env = process.env) {
+    const context = processCompanyContext(env);
+    const companyUid = companyUidForContext(context, env);
+    return {
+        ...(companyUid ? { companyUid } : {}),
+        ...(context.companySlug ? { companySlug: context.companySlug } : {}),
+    };
+}
+//# sourceMappingURL=process-flag-company-context.js.map

package/dist/lib/report-publish.d.ts

@@ -0,0 +1,175 @@
+export declare const REPORT_CSP = "default-src 'none'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-src 'none'; form-action 'none'";
+type ReportLastRun = {
+    at: string;
+    status: "running" | "succeeded" | "failed";
+    reason?: string;
+    version?: string;
+};
+export type ReportSchedule = {
+    kind: "daily" | "weekly" | "manual";
+    time: string;
+    timezone: string;
+    weekday?: number;
+};
+export type ChannelReport = {
+    reportId: string;
+    channelId: string;
+    companyUid?: string;
+    createdBy: string;
+    ownerAgentUid: string;
+    deploySlug: string;
+    state: "draft-pending" | "draft-ready" | "live" | "decommissioned";
+    instructions: string;
+    revision: number;
+    deployAppId?: string;
+    url?: string;
+    draft?: {
+        url: string;
+        appId: string;
+        generatedAt: string;
+        note?: string;
+    };
+    lastRun?: ReportLastRun;
+    jobId?: string;
+    jobState?: "pending" | "adopted" | "failed";
+    jobStateReason?: string;
+    schedule?: ReportSchedule;
+};
+export type ReportPatch = Partial<Pick<ChannelReport, "deployAppId" | "url" | "state" | "lastRun">> & {
+    previewImage?: string;
+    previewTitle?: string;
+    jobState?: "pending" | "adopted" | "failed";
+    jobStateReason?: string | null;
+    /** Null clears the live draft pointer or the adopted job id. */
+    draft?: ChannelReport["draft"] | null;
+    jobId?: string | null;
+};
+export type DeployOrgContext = {
+    headers: Record<string, string>;
+    org?: string;
+};
+export type StaticFile = {
+    path: string;
+    content: string;
+    encoding?: "utf8" | "base64";
+};
+export type ReportSource = {
+    files: StaticFile[];
+    previewTitle?: string;
+    previewImage?: string;
+};
+export type DeployAccessPolicy = {
+    mode: "company" | "selected" | "password" | "public";
+    companyUid: string;
+    users: Array<{
+        id: string;
+    }>;
+    groups: Array<{
+        id: string;
+    }>;
+    password?: string;
+};
+export type ReportDeployment = {
+    appId: string;
+    url: string;
+    deployId: string;
+};
+export interface ReportPublishDependencies {
+    patch(report: ChannelReport, patch: ReportPatch): Promise<ChannelReport>;
+    deploy(input: {
+        slug: string;
+        files: StaticFile[];
+        access: DeployAccessPolicy;
+    }): Promise<ReportDeployment>;
+    now(): string;
+    /** Owner DM for a failed run. Omitted by callers that only record lastRun. */
+    notifyOwner?(notice: {
+        to: string;
+        body: string;
+    }): Promise<void>;
+    /**
+     * PNG of the finished page for the gallery card, or null when none can be
+     * made. It is given a staged copy of the files as they will be published. Only asked for when the page does not name its own preview image.
+     */
+    snapshot?(directory: string): Promise<Buffer | null>;
+}
+/**
+ * Add a snapshot of the page as its preview when it has none of its own.
+ * A snapshot that fails never fails the publish.
+ */
+export declare function withPreviewSnapshot(source: ReportSource, snapshot: ReportPublishDependencies["snapshot"]): Promise<ReportSource>;
+/**
+ * Plain owner DM after a failed run. Suppressed for the publish lock
+ * ("already running") so a second run does not page the owner.
+ */
+export declare function ownerFailureNotice(input: {
+    code?: string | null;
+    reason: string;
+    reportUrl?: string | null;
+    ownerPersonUid: string;
+}): {
+    to: string;
+    body: string;
+} | null;
+export interface ReportAdoptDependencies {
+    preflightJobCreation(): Promise<void>;
+    createJob(input: {
+        prompt: string;
+        schedule: {
+            kind: "recurring";
+            cron: string;
+            timezone: string;
+        };
+        context: {
+            reportId: string;
+            channelId: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    cancelJob(jobId: string): Promise<void>;
+    patch(report: ChannelReport, patch: ReportPatch): Promise<ChannelReport>;
+}
+export declare class ReportPublishError extends Error {
+    readonly code: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "job-execution-disabled" | "revision-conflict";
+    constructor(message: string, code?: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "job-execution-disabled" | "revision-conflict");
+}
+/** A deliberately boring, token-safe failure reason stored on the report. */
+export declare function plainFailureReason(error: unknown): string;
+export declare function injectReportCsp(html: string): string;
+/** Read a deployable static report and inject its non-negotiable CSP. */
+export declare function loadReportSource(directory: string): ReportSource;
+/** Access policy defaults deliberately keep personal reports owner-only. */
+export declare function defaultAccessPolicy(report: ChannelReport): DeployAccessPolicy;
+export declare function reportDeploySlug(report: ChannelReport, draft: boolean): string;
+/** Source folder convention: `<bot workerDir>/reports/<reportId>/`. */
+export declare function conventionReportDir(reportId: string, workerDir?: string): string;
+/** Company deploys send X-Org-Slug; personal-channel reports have no company to gate on. */
+export declare function deployOrgContext(report: ChannelReport, companySlug?: string): DeployOrgContext;
+/**
+ * EventBridge Scheduler cron for the agent jobs API.
+ * Daily uses `?` on the weekday field; weekly pins the weekday and `?` on the day-of-month.
+ */
+export declare function reportJobCron(schedule: ReportSchedule): string | null;
+/** Job prompt is the stored update-report runbook with this report id filled in. */
+export declare function reportJobPrompt(reportId: string): string;
+/**
+ * Install, replace, or delete this bot's own scheduled job for a report.
+ * Jobs-API failures are recorded as jobState=failed with a plain reason.
+ */
+export declare function adoptReport(report: ChannelReport, deps: ReportAdoptDependencies): Promise<ChannelReport>;
+/**
+ * Lock, deploy, then persist a report run. Every known failure after lock
+ * acquisition writes a terminal lastRun so the 15-minute server TTL is a
+ * crash-only fallback rather than normal control flow.
+ */
+export declare function publishReport(report: ChannelReport, directory: string, draft: boolean, deps: ReportPublishDependencies): Promise<ChannelReport>;
+type BuiltTarball = {
+    bytes: Buffer;
+    sha256: string;
+    sizeBytes: number;
+};
+/** hq-deploy static payload format: index.html stays at the archive root. */
+export declare function buildReportTarball(files: StaticFile[]): BuiltTarball;
+export {};
+//# sourceMappingURL=report-publish.d.ts.map