@indigoai-us/hq-cli 5.323.0 → 5.324.0

package/dist/lib/registry/registry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Repo-to-company registry (hq-anywhere US-004).
+ *
+ * `~/.hq/registry.json` maps a folder to the HQ company it belongs to so a
+ * session started outside the HQ tree can bind without the user naming the
+ * company. Keys are either a normalised git remote (`remote:github.com/o/n`)
+ * or an absolute folder path (`path:/abs/dir`). Resolution never guesses:
+ * a folder with no matching entry resolves to `company: null` with a reason.
+ */
+import { type CompaniesManifestMap } from "../work-context/repo-remote.js";
+export type RegistrySource = "link" | "manifest" | "prompt";
+export interface RegistryEntry {
+    company: string;
+    source: RegistrySource;
+    linkedAt: string;
+}
+export interface Registry {
+    version: 1;
+    entries: Record<string, RegistryEntry>;
+}
+export type ResolveResult = {
+    company: string;
+    key: string;
+    source: RegistrySource;
+} | {
+    company: null;
+    reason: string;
+};
+export declare class RegistryFormatError extends Error {
+    constructor(file: string, detail: string);
+}
+/** Directory holding registry.json: HQ_REGISTRY_DIR, else ~/.hq (same parent as the work-mesh cache). */
+export declare function registryDir(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function registryFile(dir?: string): string;
+export declare function emptyRegistry(): Registry;
+/** Read the registry. A missing file is an empty registry; a malformed one throws. */
+export declare function readRegistry(file?: string): Registry;
+export declare function writeRegistry(registry: Registry, file?: string): void;
+export declare function remoteKey(normalized: string): string;
+export declare function pathKey(dir: string): string;
+/** Absolute, symlink-resolved directory path (falls back to path.resolve when missing). */
+export declare function canonicalDir(dir: string): string;
+/** Normalised origin remote for the repo enclosing `dir`, or null. */
+export declare function remoteForDir(dir: string): string | null;
+/**
+ * The key `hq link` writes for `dir`: the remote key when inside a git repo
+ * with a recognised origin, otherwise the path key (work-tree root when inside
+ * a repo without an origin, else the folder itself).
+ */
+export declare function keyForDir(dir: string): string;
+/** Every key that could describe `dir`, most specific first. */
+export declare function candidateKeys(dir: string): string[];
+/**
+ * Resolve the company for `dir`. Among matching keys the highest-ranked source
+ * wins (link > prompt > manifest); ties go to the more specific key.
+ */
+export declare function resolveCompanyForDir(registry: Registry, dir: string): ResolveResult;
+export declare function setEntry(registry: Registry, key: string, company: string, source: RegistrySource, now?: Date): RegistryEntry;
+/** Remove every key that describes `dir`. Returns the removed keys. */
+export declare function removeEntriesForDir(registry: Registry, dir: string): string[];
+export interface SeedResult {
+    added: string[];
+    owned: string[];
+    skippedLinked: string[];
+    ambiguous: string[];
+}
+/**
+ * Seed manifest-sourced entries from companies/manifest.yaml repos[]. Entries
+ * may be HQ-relative paths (`repos/private/x`), `owner/name`, or remote URLs.
+ * A local path seeds both its path key and, when it has an origin, its remote
+ * key. Never overwrites a `link` or `prompt` entry, and skips any key claimed
+ * by more than one company.
+ */
+export declare function seedFromManifest(registry: Registry, hqRoot: string, companies: CompaniesManifestMap, now?: Date): SeedResult;
+//# sourceMappingURL=registry.d.ts.map

package/dist/lib/registry/registry.js

@@ -0,0 +1,261 @@
+/**
+ * Repo-to-company registry (hq-anywhere US-004).
+ *
+ * `~/.hq/registry.json` maps a folder to the HQ company it belongs to so a
+ * session started outside the HQ tree can bind without the user naming the
+ * company. Keys are either a normalised git remote (`remote:github.com/o/n`)
+ * or an absolute folder path (`path:/abs/dir`). Resolution never guesses:
+ * a folder with no matching entry resolves to `company: null` with a reason.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { atomicWriteJson } from "../work-context/atomic.js";
+import { findEnclosingGitDir, findWorkTreeRoot, readOriginRemoteUrl, } from "../work-context/repo-remote.js";
+import { normalizeManifestRepo, normalizeRemoteUrl } from "./normalize-remote.js";
+/** Higher wins. An explicit `hq link` beats a prompt answer beats the manifest seed. */
+const SOURCE_RANK = { link: 3, prompt: 2, manifest: 1 };
+export class RegistryFormatError extends Error {
+    constructor(file, detail) {
+        super(`HQ registry at ${file} is unreadable: ${detail}`);
+        this.name = "RegistryFormatError";
+    }
+}
+/** Directory holding registry.json: HQ_REGISTRY_DIR, else ~/.hq (same parent as the work-mesh cache). */
+export function registryDir(home = os.homedir(), env = process.env) {
+    const override = env.HQ_REGISTRY_DIR?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(home, ".hq");
+}
+export function registryFile(dir = registryDir()) {
+    return path.join(dir, "registry.json");
+}
+export function emptyRegistry() {
+    return { version: 1, entries: {} };
+}
+function isSource(value) {
+    return value === "link" || value === "manifest" || value === "prompt";
+}
+/** Read the registry. A missing file is an empty registry; a malformed one throws. */
+export function readRegistry(file = registryFile()) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return emptyRegistry();
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new RegistryFormatError(file, err.message);
+    }
+    const rawEntries = parsed?.entries;
+    if (!rawEntries || typeof rawEntries !== "object" || Array.isArray(rawEntries)) {
+        throw new RegistryFormatError(file, "missing `entries` object");
+    }
+    const entries = {};
+    for (const [key, value] of Object.entries(rawEntries)) {
+        const rec = value;
+        if (!rec || typeof rec.company !== "string" || !rec.company || !isSource(rec.source)) {
+            throw new RegistryFormatError(file, `invalid entry for ${key}`);
+        }
+        entries[key] = {
+            company: rec.company,
+            source: rec.source,
+            linkedAt: typeof rec.linkedAt === "string" ? rec.linkedAt : "",
+        };
+    }
+    return { version: 1, entries };
+}
+export function writeRegistry(registry, file = registryFile()) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const sorted = {};
+    for (const key of Object.keys(registry.entries).sort())
+        sorted[key] = registry.entries[key];
+    atomicWriteJson(file, { version: 1, entries: sorted });
+}
+export function remoteKey(normalized) {
+    return `remote:${normalized}`;
+}
+export function pathKey(dir) {
+    return `path:${canonicalDir(dir)}`;
+}
+/** Absolute, symlink-resolved directory path (falls back to path.resolve when missing). */
+export function canonicalDir(dir) {
+    const abs = path.resolve(dir);
+    try {
+        return fs.realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** Normalised origin remote for the repo enclosing `dir`, or null. */
+export function remoteForDir(dir) {
+    const gitDir = findEnclosingGitDir(dir);
+    if (!gitDir)
+        return null;
+    // Linked worktrees keep their config in the common dir.
+    const commonFile = path.join(gitDir, "commondir");
+    let configDir = gitDir;
+    try {
+        const common = fs.readFileSync(commonFile, "utf8").trim();
+        if (common)
+            configDir = path.resolve(gitDir, common);
+    }
+    catch {
+        // Not a linked worktree.
+    }
+    const origin = readOriginRemoteUrl(configDir) ?? readOriginRemoteUrl(gitDir);
+    return origin ? normalizeRemoteUrl(origin) : null;
+}
+/**
+ * The key `hq link` writes for `dir`: the remote key when inside a git repo
+ * with a recognised origin, otherwise the path key (work-tree root when inside
+ * a repo without an origin, else the folder itself).
+ */
+export function keyForDir(dir) {
+    const remote = remoteForDir(dir);
+    if (remote)
+        return remoteKey(remote);
+    return pathKey(findWorkTreeRoot(dir) ?? dir);
+}
+/** Every key that could describe `dir`, most specific first. */
+export function candidateKeys(dir) {
+    const keys = [pathKey(dir)];
+    const workTree = findWorkTreeRoot(dir);
+    if (workTree)
+        keys.push(pathKey(workTree));
+    const remote = remoteForDir(dir);
+    if (remote)
+        keys.push(remoteKey(remote));
+    return [...new Set(keys)];
+}
+/**
+ * Resolve the company for `dir`. Among matching keys the highest-ranked source
+ * wins (link > prompt > manifest); ties go to the more specific key.
+ */
+export function resolveCompanyForDir(registry, dir) {
+    let best = null;
+    for (const key of candidateKeys(dir)) {
+        const entry = registry.entries[key];
+        if (!entry)
+            continue;
+        if (!best || SOURCE_RANK[entry.source] > SOURCE_RANK[best.entry.source]) {
+            best = { key, entry };
+        }
+    }
+    if (!best) {
+        return {
+            company: null,
+            reason: `No HQ company is linked to ${canonicalDir(dir)}. Run \`hq link <company>\` there.`,
+        };
+    }
+    return { company: best.entry.company, key: best.key, source: best.entry.source };
+}
+export function setEntry(registry, key, company, source, now = new Date()) {
+    const entry = { company, source, linkedAt: now.toISOString() };
+    registry.entries[key] = entry;
+    return entry;
+}
+/** Remove every key that describes `dir`. Returns the removed keys. */
+export function removeEntriesForDir(registry, dir) {
+    const removed = [];
+    for (const key of candidateKeys(dir)) {
+        if (registry.entries[key]) {
+            delete registry.entries[key];
+            removed.push(key);
+        }
+    }
+    return removed;
+}
+/**
+ * Seed manifest-sourced entries from companies/manifest.yaml repos[]. Entries
+ * may be HQ-relative paths (`repos/private/x`), `owner/name`, or remote URLs.
+ * A local path seeds both its path key and, when it has an origin, its remote
+ * key. Never overwrites a `link` or `prompt` entry, and skips any key claimed
+ * by more than one company.
+ */
+export function seedFromManifest(registry, hqRoot, companies, now = new Date()) {
+    const claimGroups = [];
+    for (const [company, entry] of Object.entries(companies)) {
+        const repos = entry && typeof entry === "object" ? entry.repos : undefined;
+        if (!Array.isArray(repos))
+            continue;
+        for (const raw of repos) {
+            if (typeof raw !== "string" || !raw.trim())
+                continue;
+            const trimmed = raw.trim();
+            const local = path.isAbsolute(trimmed) ? trimmed : path.join(hqRoot, trimmed);
+            let isDir;
+            try {
+                isDir = fs.statSync(local).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+            if (isDir) {
+                const keys = [pathKey(local)];
+                const remote = remoteForDir(local);
+                if (remote)
+                    keys.push(remoteKey(remote));
+                claimGroups.push({ company, keys });
+                continue;
+            }
+            const normalized = normalizeManifestRepo(trimmed);
+            if (normalized)
+                claimGroups.push({ company, keys: [remoteKey(normalized)] });
+        }
+    }
+    const claims = new Map();
+    for (const group of claimGroups) {
+        for (const key of group.keys) {
+            const set = claims.get(key) ?? new Set();
+            set.add(group.company);
+            claims.set(key, set);
+        }
+    }
+    const ambiguous = new Set([...claims].filter(([, companies]) => companies.size > 1).map(([key]) => key));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const group of claimGroups) {
+            if (group.keys.some((key) => ambiguous.has(key))) {
+                for (const key of group.keys) {
+                    if (!ambiguous.has(key)) {
+                        ambiguous.add(key);
+                        changed = true;
+                    }
+                }
+            }
+        }
+    }
+    const result = { added: [], owned: [], skippedLinked: [], ambiguous: [...ambiguous].sort() };
+    const unambiguousClaims = new Map();
+    for (const group of claimGroups) {
+        if (group.keys.some((key) => ambiguous.has(key)))
+            continue;
+        for (const key of group.keys)
+            unambiguousClaims.set(key, group.company);
+    }
+    for (const [key, company] of unambiguousClaims) {
+        const existing = registry.entries[key];
+        if (existing && existing.source !== "manifest") {
+            result.skippedLinked.push(key);
+            continue;
+        }
+        if (existing?.company !== company) {
+            setEntry(registry, key, company, "manifest", now);
+            result.added.push(key);
+        }
+        result.owned.push(key);
+    }
+    return result;
+}
+//# sourceMappingURL=registry.js.map

package/dist/utils/cognito-session.d.ts

@@ -237,6 +237,9 @@ export declare function withMachineTokenStateDir<T>(fn: () => Promise<T>, opts?:
     home?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<T>;
+type MachineTokenValidityOptions = {
+    minValiditySeconds?: number;
+};
 /**
  * Ensure the current machine identity has a valid session and return only the
  * access/ID token pair needed by supported machine-session handoff scripts.
@@ -294,7 +297,8 @@ export declare function buildVaultConfig(authToken: string): VaultServiceConfig;
  * means no valid session could be ensured non-interactively; the caller gets a
  * reason string and can decide what to do next. Never opens a browser.
  */
-export declare function refreshCachedSession(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">): Promise<{
+type MachineRefreshOptions = Pick<EnsureCognitoTokenOptions, "tokenSource"> & MachineTokenValidityOptions;
+export declare function refreshCachedSession(options?: MachineRefreshOptions): Promise<{
     refreshed: boolean;
     reason?: string;
 }>;

package/dist/utils/cognito-session.js

@@ -837,8 +837,12 @@ function withTokenStateDirSection(fn) {
     tokenStateDirTail = run.catch(() => undefined);
     return run;
 }
-async function ensureMachineTokens() {
-    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO));
+const MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS = 1800;
+async function ensureMachineTokens(minValiditySeconds) {
+    const resolverMinimum = minValiditySeconds === undefined
+        ? undefined
+        : Math.min(minValiditySeconds, MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS);
+    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO, resolverMinimum === undefined ? undefined : { minValiditySeconds: resolverMinimum }));
 }
 /**
  * Ensure the current machine identity has a valid session and return only the
@@ -857,7 +861,7 @@ async function ensureMachineTokensMaybeFallback(options = {}) {
     if (isDefaultMachineCredsFallback(options)) {
         logDefaultMachineCredsFallback();
     }
-    return ensureMachineTokens();
+    return ensureMachineTokens(options.minValiditySeconds);
 }
 /**
  * After a person-cache miss or refresh failure: if the default machine-creds
@@ -872,7 +876,7 @@ async function tryDefaultMachineCredsFallback(options = {}) {
     if (!isMachineIdentity())
         return null;
     logDefaultMachineCredsFallback();
-    return ensureMachineTokens();
+    return ensureMachineTokens(options.minValiditySeconds);
 }
 /**
  * True when a person-token refresh failed with a definitive Cognito auth
@@ -1114,14 +1118,6 @@ export function buildVaultConfig(authToken) {
         clientInfo: CLI_CLIENT_INFO,
     };
 }
-/**
- * Ensure a valid cached Cognito session exists right now, non-interactively,
- * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
- * bin. `refreshed: true` means a valid session is ensured now from a healthy
- * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
- * means no valid session could be ensured non-interactively; the caller gets a
- * reason string and can decide what to do next. Never opens a browser.
- */
 export async function refreshCachedSession(options = {}) {
     if (wantsMachineCognitoTokens(options))
         return refreshCachedSessionUnserialized(options);

package/dist/utils/feedback-diagnostics.d.ts

@@ -8,6 +8,8 @@ interface GitContext {
 }
 export interface DiagnosticsBlob {
     cliVersion: string;
+    /** Current npm release, included only when the feedback.latest-version flag is enabled. */
+    latestVersion?: string;
     /**
      * The hq-cli, hq-core, and hq-sync versions from the submitter's
      * environment. `cliVersion` above is retained for back-compat; new

package/dist/utils/version-check.d.ts

@@ -1,5 +1,7 @@
 export declare const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
 declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boolean;
+/** Return the fresh npm `latest` already cached by the startup update check. */
+export declare function cachedLatestVersion(now?: number): string | null;
 /**
  * The cached npm `latest` when it is newer than the running version, else null.
  *

package/dist/utils/version-check.js

@@ -111,6 +111,13 @@ function acquireRefreshLock(now = Date.now()) {
         return null;
     }
 }
+/** Return the fresh npm `latest` already cached by the startup update check. */
+export function cachedLatestVersion(now = Date.now()) {
+    const entry = readCache();
+    if (!entry || now - entry.fetchedAt > CACHE_TTL_MS)
+        return null;
+    return semver.valid(entry.latest) ? entry.latest : null;
+}
 /**
  * The cached npm `latest` when it is newer than the running version, else null.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.323.0",
+  "version": "5.324.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -44,7 +44,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.18.17",
+    "@indigoai-us/hq-cloud": "~6.18.33",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",