@indigoai-us/hq-cli 5.220.0 → 5.221.0

package/dist/commands/lanes.d.ts

@@ -12,7 +12,7 @@ export type { OutpostIdentity } from "../lib/lanes/admission-host.js";
 export { LANE_HIRE_GRANTS_FLAG };
 import { type OutpostDispatchResult } from "../lib/lanes/outpost-dispatch.js";
 import { emitLaneDecisionEvents, type LaneMesh } from "../lib/lanes/mesh-events.js";
-import { LANE_HIRE_GRANTS_FLAG, MAX_LANE_DEPTH, withLaneHireLocks, type LaneCompanyRef, type LaneRecord, type QuestionRecord, type ResolvedLaneWorker, type SeniorRef, type LivenessDeps, type MachineIdentity, type MonitorEvidenceReader, type RunCommand, type ThrottleDeps } from "../lib/lanes/index.js";
+import { LANE_HIRE_GRANTS_FLAG, MAX_LANE_DEPTH, withLaneHireLocks, type LaneCompanyRef, type QuestionBody, type LaneRecord, type QuestionRecord, type ResolvedLaneWorker, type SeniorRef, type LivenessDeps, type MachineIdentity, type MonitorEvidenceReader, type RunCommand, type ThrottleDeps } from "../lib/lanes/index.js";
 import { questionBodyAbsPath } from "../lib/lanes/questions.js";
 import { type RunCompactionFn } from "../lib/lanes/compaction.js";
 import { type KnownModelsDeps, type ProbeCommand } from "../lib/lanes/models.js";
@@ -107,6 +107,7 @@ export declare const LANE_OUTPOST_QUESTION_VISIBILITY_FLAG = "lanes.outpost-ques
 export declare const LANE_HOST_SCOPED_ACCOUNT_HOMES_FLAG = "lanes.host-scoped-account-homes";
 export declare function parseSeniorRef(raw: string): SeniorRef;
 export declare function resolveAnswerChoice(choice: string, options: string[], freeform: boolean): string;
+export declare function parseQuestionBody(raw: unknown): QuestionBody | null;
 /**
  * Spec §5.1: `hq lanes ask` from inside a lane can hit a binary or dist
  * being replaced mid-call (ENOENT / ETXTBSY / a module that no longer

package/dist/commands/lanes.js

@@ -14,6 +14,7 @@ import { readLocalOverride } from "@indigoai-us/hq-flags-client";
 import { Option } from "commander";
 import { registerOutpostPrunerCommand } from "./outpost-pruner.js";
 import { registerLaneChecksCommand } from "./lanes-checks.js";
+import { registerLaneReportCommands } from "./lanes-report.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
@@ -43,6 +44,7 @@ import { activeLaneStories, laneStories, laneStory, storyWarning, } from "../lib
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
 import { keepAliveExclusion, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
 import { questionBodyAbsPath, resolveQuestionCompanyWithFallback, resolveProjectQuestionCompany, } from "../lib/lanes/questions.js";
+import { assertQuestionBodySecretSafe } from "../lib/lanes/questions.js";
 import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
 import { assertUniqueAccountHomes, providerCompactAfterMs } from "../lib/lanes/config.js";
 import { parseCliEffort, resolveLaneEffort, } from "../lib/lanes/effort.js";
@@ -438,16 +440,20 @@ function readJsonFile(filePath) {
         throw err;
     }
 }
-function parseQuestionBody(raw) {
+export function parseQuestionBody(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw))
         return null;
     const obj = raw;
-    const options = Array.isArray(obj.options)
-        ? obj.options.filter((item) => typeof item === "string")
-        : [];
+    if (typeof obj.question !== "string" || typeof obj.context !== "string" || !Array.isArray(obj.options) || obj.options.some((item) => typeof item !== "string"))
+        return null;
+    if (obj.recommended !== undefined && typeof obj.recommended !== "string")
+        return null;
+    if (obj.notes !== undefined && typeof obj.notes !== "string")
+        return null;
+    const options = obj.options.filter((item) => typeof item === "string");
     const body = {
-        question: typeof obj.question === "string" ? obj.question : "",
-        context: typeof obj.context === "string" ? obj.context : "",
+        question: obj.question,
+        context: obj.context,
         options,
     };
     if (typeof obj.recommended === "string")
@@ -8506,6 +8512,18 @@ export function registerLanesCommand(parent, deps = {}) {
         trackerMeshEnabled: ctx.laneTrackerMeshEnabled,
         now: ctx.now,
     }, wrap);
+    registerLaneReportCommands(lanes, {
+        hqRoot: ctx.hqRoot,
+        resolveCompany: ctx.resolveCompany,
+        trackerEnabled: ctx.laneTrackerEnabled,
+        trackerMeshEnabled: ctx.laneTrackerMeshEnabled,
+        now: ctx.now,
+        readQuestionBody: (root, question) => {
+            const body = requireQuestionBody(root, question);
+            assertQuestionBodySecretSafe(body);
+            return body;
+        },
+    }, wrap);
     registerOutpostPrunerCommand(lanes);
     const noStoryOption = new Option("--no-story <reason>", "Create a lane without a story and record why");
     noStoryOption.attributeName = () => "noStory";

package/dist/lib/lanes/timestamp.d.ts

@@ -0,0 +1,3 @@
+/** Parse an extended ISO timestamp and return JavaScript's canonical UTC form. */
+export declare function normalizeIsoTimestamp(value: unknown): string | null;
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/lib/lanes/timestamp.js

@@ -0,0 +1,26 @@
+/** Parse an extended ISO timestamp and return JavaScript's canonical UTC form. */
+export function normalizeIsoTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)(?:\.(\d+))?(Z|([+-])(\d\d):(\d\d))$/.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const offsetHour = match[9] === undefined ? 0 : Number(match[10]);
+    const offsetMinute = match[9] === undefined ? 0 : Number(match[11]);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+    if (month < 1 || month > 12 || day < 1 || daysInMonth === undefined || day > daysInMonth ||
+        hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59)
+        return null;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return null;
+    return new Date(parsed).toISOString();
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/lib/lanes/tracker-report-state.d.ts

@@ -0,0 +1,10 @@
+export declare const FIRST_TRACKER_REPORT_SINCE = "1970-01-01T00:00:00.000Z";
+export interface TrackerReportState {
+    schema_version: "hq-lanes-report-state.v1";
+    company: string;
+    last_report_at: string;
+}
+export declare function trackerReportStatePath(root: string, company: string): string;
+export declare function readTrackerReportState(root: string, company: string): TrackerReportState | null;
+export declare function writeTrackerReportState(root: string, company: string, at: string): TrackerReportState;
+//# sourceMappingURL=tracker-report-state.d.ts.map

package/dist/lib/lanes/tracker-report-state.js

@@ -0,0 +1,124 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { LanesError } from "./errors.js";
+import { normalizeIsoTimestamp } from "./timestamp.js";
+export const FIRST_TRACKER_REPORT_SINCE = "1970-01-01T00:00:00.000Z";
+export function trackerReportStatePath(root, company) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(company) || company === "." || company === "..") {
+        throw new LanesError("tracker_report_company_invalid", "Company slug must be a safe path segment", { company });
+    }
+    return path.join(root, "workspace", "lane-briefs", "tracker-report-state", `${company}.json`);
+}
+function stateError(error, message, file) {
+    throw new LanesError(error, `${message}: ${file}`, { path: file });
+}
+function validReportTime(value, file) {
+    const normalized = normalizeIsoTimestamp(value);
+    if (normalized === null) {
+        return stateError("tracker_report_state_invalid", "Report state has an invalid last_report_at", file);
+    }
+    return normalized;
+}
+export function readTrackerReportState(root, company) {
+    const file = trackerReportStatePath(root, company);
+    if (stateDirectory(root, false) === null)
+        return null;
+    let raw;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            return stateError("tracker_report_state_invalid", "Report state path must be a regular file", file);
+        }
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        if (err instanceof LanesError)
+            throw err;
+        return stateError("tracker_report_state_unreadable", `Report state could not be read: ${err instanceof Error ? err.message : String(err)}`, file);
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return stateError("tracker_report_state_malformed", "Report state contains invalid JSON", file);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return stateError("tracker_report_state_invalid", "Report state must be an object", file);
+    }
+    const record = value;
+    if (record.schema_version !== "hq-lanes-report-state.v1" || record.company !== company) {
+        return stateError("tracker_report_state_invalid", "Report state schema or company does not match", file);
+    }
+    return {
+        schema_version: "hq-lanes-report-state.v1",
+        company,
+        last_report_at: validReportTime(record.last_report_at, file),
+    };
+}
+function stateDirectory(root, create) {
+    let rootReal;
+    try {
+        rootReal = fs.realpathSync(root);
+    }
+    catch (err) {
+        return stateError("tracker_report_state_root_invalid", `HQ root could not be resolved: ${err instanceof Error ? err.message : String(err)}`, root);
+    }
+    let current = rootReal;
+    for (const segment of ["workspace", "lane-briefs", "tracker-report-state"]) {
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (err) {
+            if (err.code === "ENOENT" && !create)
+                return null;
+            if (err.code !== "ENOENT") {
+                return stateError("tracker_report_state_path_unreadable", `Report state directory could not be inspected: ${err instanceof Error ? err.message : String(err)}`, current);
+            }
+            try {
+                fs.mkdirSync(current, { mode: 0o700 });
+            }
+            catch (mkdirError) {
+                return stateError("tracker_report_state_path_unwritable", `Report state directory could not be created: ${mkdirError instanceof Error ? mkdirError.message : String(mkdirError)}`, current);
+            }
+            stat = fs.lstatSync(current);
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            return stateError("tracker_report_state_path_invalid", "Report state directory must be a real directory", current);
+        }
+    }
+    return current;
+}
+export function writeTrackerReportState(root, company, at) {
+    const canonicalAt = validReportTime(at, trackerReportStatePath(root, company));
+    const directory = stateDirectory(root, true);
+    if (directory === null)
+        return stateError("tracker_report_state_path_unavailable", "Report state directory is unavailable", trackerReportStatePath(root, company));
+    const file = trackerReportStatePath(root, company);
+    const temp = path.join(directory, `.${company}.${randomUUID()}.tmp`);
+    const value = { schema_version: "hq-lanes-report-state.v1", company, last_report_at: canonicalAt };
+    try {
+        fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        fs.renameSync(temp, file);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== "ENOENT") {
+                throw new LanesError("tracker_report_state_cleanup_failed", `Report state temporary file could not be removed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`, { path: temp });
+            }
+        }
+        if (err instanceof LanesError)
+            throw err;
+        return stateError("tracker_report_state_write_failed", `Report state could not be written: ${err instanceof Error ? err.message : String(err)}`, file);
+    }
+    return value;
+}
+//# sourceMappingURL=tracker-report-state.js.map

package/dist/lib/lanes/tracker-report.d.ts

@@ -0,0 +1,203 @@
+import type { QuestionBody } from "./questions.js";
+import type { QuestionRecord } from "./types.js";
+import type { TrackerRecord } from "./tracker-store.js";
+export type ReportStoryStatus = "queued" | "in_progress" | "review" | "done" | "dropped";
+export type ReportAudience = "owner" | "operator" | "lane";
+export type ApprovalState = "proposal" | "approved";
+export interface TrackerReportRecord extends TrackerRecord {
+    /** Absolute path of the validated on-disk record; used only in errors. */
+    source_path: string;
+}
+export interface TrackerReportStory {
+    id: string;
+    title: string;
+    status: ReportStoryStatus;
+    references?: string[];
+    updated_at?: string;
+    source_path: string;
+}
+export interface TrackerReportIssue {
+    path: string;
+    field: string;
+    message: string;
+    story_id?: string;
+    record_id?: string;
+    question_id?: string;
+}
+export interface TrackerReportPullRequest {
+    number: string;
+    title: string;
+    merged_at: string;
+    source_path: string;
+}
+export interface TrackerReportRelease {
+    version: string;
+    released_at: string;
+    source_path: string;
+}
+export interface TrackerReportQuestion {
+    record: QuestionRecord;
+    /** Loaded through the existing company-checked question body reader. */
+    body: QuestionBody;
+    current_audience: ReportAudience;
+    source_path: string;
+}
+export interface TrackerReportTeamInput {
+    company: string;
+    team: string;
+    project_id: string;
+    stories: readonly TrackerReportStory[];
+    pull_requests: readonly TrackerReportPullRequest[];
+    releases: readonly TrackerReportRelease[];
+    blockers: readonly TrackerReportRecord[];
+    kpis: readonly TrackerReportRecord[];
+    okrs: readonly TrackerReportRecord[];
+    directives: readonly TrackerReportRecord[];
+    questions: readonly TrackerReportQuestion[];
+    errors?: readonly TrackerReportIssue[];
+}
+export interface TrackerReportInput {
+    company: string;
+    generated_at: string;
+    since: string;
+    since_source: "explicit" | "previous_report" | "first_run";
+    teams: readonly TrackerReportTeamInput[];
+}
+export interface ReportTimedStory {
+    id: string;
+    title: string;
+    at: string;
+    references: string[];
+}
+export interface ReportPullRequest {
+    number: string;
+    title: string;
+    merged_at: string;
+}
+export interface ReportRelease {
+    version: string;
+    released_at: string;
+}
+export interface ReportKpiValue {
+    kpi_id: string;
+    name: string;
+    at: string;
+    value: number;
+    unit: string;
+    source: string;
+}
+export interface ReportQuestion {
+    question_id: string;
+    question: string;
+    asked_at: string;
+    audience: ReportAudience;
+    options: string[];
+    recommended?: string;
+    answer?: {
+        choice: string;
+        answered_at: string;
+        answered_by: string;
+    };
+}
+export interface ReportBlocker {
+    id: string;
+    story_id: string;
+    what: string;
+    waiting_on: string;
+    next_step: string;
+    opened_at: string;
+}
+export interface ReportDirective {
+    id: string;
+    text: string;
+    date: string;
+    acknowledgements: Array<{
+        team: string;
+        lane_id: string;
+        at: string;
+    }>;
+}
+export interface TrackerOwnerTeamReport {
+    team: string;
+    project_id: string;
+    errors: TrackerReportIssue[];
+    progress: {
+        stories_moved_to_done: ReportTimedStory[];
+        pull_requests_merged: ReportPullRequest[];
+        releases: ReportRelease[];
+        kpi_values: ReportKpiValue[];
+    };
+    questions_waiting_on_owner: ReportQuestion[];
+    open_blockers: ReportBlocker[];
+    decisions: {
+        directives: ReportDirective[];
+        answered_questions: ReportQuestion[];
+    };
+}
+export interface TrackerOwnerReport {
+    schema_version: "hq-lanes-owner-report.v1";
+    company: string;
+    generated_at: string;
+    since: string;
+    since_source: TrackerReportInput["since_source"];
+    teams: TrackerOwnerTeamReport[];
+}
+export interface TrackerTeamKpi {
+    id: string;
+    name: string;
+    definition: string;
+    unit: string;
+    target: number;
+    direction: "up" | "down";
+    status: ApprovalState;
+    latest_value: {
+        at: string;
+        value: number;
+        source: string;
+    } | null;
+    recent_values: Array<{
+        at: string;
+        value: number;
+        source: string;
+    }>;
+    trend: "improving" | "regressing" | "flat" | "insufficient_data";
+}
+export interface TrackerTeamOkr {
+    id: string;
+    objective: string;
+    period: string;
+    status: ApprovalState;
+    key_results: Array<{
+        text: string;
+        kpi_id: string;
+        target: number;
+    }>;
+}
+export interface TrackerTeamPage {
+    schema_version: "hq-lanes-team-page.v1";
+    company: string;
+    team: string;
+    project_id: string;
+    since: string;
+    errors: TrackerReportIssue[];
+    okrs: TrackerTeamOkr[];
+    kpis: TrackerTeamKpi[];
+    work_in_progress: Array<{
+        id: string;
+        title: string;
+        status: ReportStoryStatus;
+        references: string[];
+    }>;
+    work_done_since: ReportTimedStory[];
+    blockers: ReportBlocker[];
+    questions: ReportQuestion[];
+}
+/** Pure report projection. The caller owns loading, tenant checks, body reads and report-time persistence. */
+export declare function buildTrackerOwnerReport(input: TrackerReportInput): TrackerOwnerReport;
+/** Pure team page projection for already loaded, company-checked records. */
+export declare function buildTrackerTeamPage(team: TrackerReportTeamInput, company: string, sinceValue: string, generatedAtValue: string): TrackerTeamPage;
+/** Human-readable owner report, rendered without editing after the command runs. */
+export declare function renderTrackerOwnerReportText(report: TrackerOwnerReport): string;
+/** Human-readable team page, with proposal status visible beside each objective and KPI. */
+export declare function renderTrackerTeamPageText(page: TrackerTeamPage): string;
+//# sourceMappingURL=tracker-report.d.ts.map