@indigoai-us/hq-cli 5.220.0 → 5.222.0

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