@indigoai-us/hq-cli 5.280.0 → 5.281.0

package/assets/scaffold/core/scripts/ontology-source-worklist.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# ontology-source-worklist.sh — list a declared source's unprocessed items with
+# each item's resolved audience. The ontology worker's process-source skill
+# reads this list, extracts candidates from each item, and marks it done.
+# Specs: source-yaml-spec.md, ontology-local-spec.md (core/knowledge/public/hq-core/)
+#
+# Usage:
+#   ontology-source-worklist.sh --company <co> --channel <ch> [--limit N] [--force]
+#   ontology-source-worklist.sh --company <co> --channel <ch> --mark-done <item-file>
+#
+# Output: one JSON object per line:
+#   {"file":"sources/meetings/x.md","audience_key":"…","audience":["prs_…","a@x.com"]}
+#   {"file":"sources/meetings/y.md","skip":"no-audience"}
+# Audience by audience_rule:
+#   attendees / thread / channel — the item's `audience:` or `attendees:` list if
+#     it has one, else the direct read grants on the item's vault key
+#     (hq files acl), which is how cloud ingestion records who was privy.
+#   explicit — the item's own `audience:` frontmatter only.
+#   company  — "company".
+# An item with no resolvable audience is emitted as a skip, never as company.
+# Exit 0; 2 bad usage / invalid source.yaml; 4 run: cloud source without --force.
+set -uo pipefail
+HQ="${HQ_BIN:-hq}"
+root="${HQ_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+here="$(cd "$(dirname "$0")" && pwd)"
+co="" ch="" limit=50 force=0 done_item=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --company) co="$2"; shift 2 ;; --channel) ch="$2"; shift 2 ;; --limit) limit="$2"; shift 2 ;;
+    --force) force=1; shift ;; --mark-done) done_item="$2"; shift 2 ;;
+    *) echo "unknown flag $1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$co" ] && [ -n "$ch" ] || { echo "usage: ontology-source-worklist.sh --company <co> --channel <ch> [--limit N] [--force] [--mark-done <file>]" >&2; exit 2; }
+D="$root/companies/$co/sources/$ch"; Y="$D/source.yaml"; ledger="$D/.processed"
+bash "$here/source-yaml-validate.sh" "$Y" >/dev/null || { bash "$here/source-yaml-validate.sh" "$Y" >&2; exit 2; }
+
+if [ -n "$done_item" ]; then echo "$(basename "$done_item")" >> "$ledger"; exit 0; fi
+
+get() { awk -v k="$1" '$0 ~ "^"k":" { sub("^"k":[[:space:]]*", ""); gsub(/^["\x27]|["\x27]$/, ""); print; exit }' "$Y"; }
+run="$(get run)"; rule="$(get audience_rule)"
+if [ "$run" = cloud ] && [ "$force" = 0 ]; then echo "assigned to cloud agent (run: cloud); pass --force to run locally" >&2; exit 4; fi
+
+item_list() { # frontmatter list field: inline [a, b] or block "- a"
+  awk -v k="$2" '
+    BEGIN{fm=0}
+    /^---$/ { fm++; if (fm==2) exit; next }
+    fm==1 && $0 ~ "^"k":" { v=$0; sub("^"k":[[:space:]]*", "", v)
+      if (v ~ /^\[/) { gsub(/[\[\]"\x27]/, "", v); n=split(v, a, ","); for(i=1;i<=n;i++){gsub(/^[ \t]+|[ \t]+$/, "", a[i]); if(a[i]!="") print a[i]}; exit }
+      inlist=1; next }
+    fm==1 && inlist && /^[[:space:]]*-[[:space:]]/ { v=$0; sub(/^[[:space:]]*-[[:space:]]*/, "", v); gsub(/["\x27]/, "", v); print v; next }
+    fm==1 && inlist { exit }
+  ' "$1"
+}
+
+n=0
+for f in "$D"/*.md; do
+  [ -f "$f" ] || continue
+  b="$(basename "$f")"
+  [ -f "$ledger" ] && grep -qxF "$b" "$ledger" && continue
+  [ "$n" -ge "$limit" ] && break
+  n=$((n+1))
+  rel="sources/$ch/$b"
+  aud=""
+  case "$rule" in
+    company) aud="company" ;;
+    explicit) aud="$(item_list "$f" audience | paste -sd, -)" ;;
+    *)
+      aud="$(item_list "$f" audience | paste -sd, -)"
+      [ -n "$aud" ] || aud="$(item_list "$f" attendees | grep -E '@|^(prs|agt)_' | paste -sd, -)"
+      if [ -z "$aud" ]; then
+        aud="$("$HQ" files --company "$co" acl "$rel" --json 2>/dev/null \
+          | jq -r '[.direct[]? | select(.granteeType=="person" or .granteeType=="email" or .granteeType=="agent") | select(.permission=="read" or .permission=="write" or .permission=="admin") | .granteeId] | unique | join(",")' 2>/dev/null)"
+      fi ;;
+  esac
+  if [ -z "$aud" ]; then jq -cn --arg f "$rel" '{file:$f, skip:"no-audience"}'; continue; fi
+  key="$(HQ_ROOT="$root" bash "$here/ontology-candidate.sh" key "$aud")"
+  jq -cn --arg f "$rel" --arg k "$key" --arg a "$aud" '{file:$f, audience_key:$k, audience:($a|split(","))}'
+done

package/assets/scaffold/core/scripts/source-yaml-validate.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# source-yaml-validate.sh — validate a sources/{channel}/source.yaml.
+# Spec: core/knowledge/public/hq-core/source-yaml-spec.md
+# Usage: source-yaml-validate.sh <path/to/source.yaml>
+# Exit 0 valid; 1 invalid (each violation printed); 2 bad usage / missing file.
+set -uo pipefail
+f="${1:-}"
+[ -n "$f" ] || { echo "usage: source-yaml-validate.sh <source.yaml>" >&2; exit 2; }
+[ -f "$f" ] || { echo "source-yaml-validate: no such file $f" >&2; exit 2; }
+
+get() {
+  awk -v k="$1" '$0 ~ "^"k":" { sub("^"k":[[:space:]]*", ""); sub("[[:space:]]+#.*$", ""); gsub(/^["\x27]|["\x27]$/, ""); print; exit }' "$f"
+}
+v=0
+bad() { echo "$f: $*"; v=$((v+1)); }
+oneof() { case " $3 " in *" $2 "*) ;; *) bad "$1 must be one of: $3 (got '${2:-<missing>}')" ;; esac; }
+
+channel="$(get channel)"; kind="$(get kind)"; arrives="$(get arrives)"; pull="$(get pull_command)"
+aud="$(get audience_rule)"; proc="$(get processor)"; run="$(get run)"; sched="$(get schedule)"
+
+[ -n "$channel" ] || bad "channel is required"
+folder="$(basename "$(dirname "$f")")"
+[ -z "$channel" ] || [ "$channel" = "$folder" ] || bad "channel '$channel' must equal its folder name '$folder'"
+oneof kind "$kind" "meeting email slack doc custom"
+oneof arrives "$arrives" "drop pull cloud"
+[ "$arrives" != pull ] || [ -n "$pull" ] || bad "pull_command is required when arrives: pull"
+[ -n "$aud" ] || bad "audience_rule is required (attendees|thread|channel|company|explicit); it is never defaulted"
+[ -z "$aud" ] || oneof audience_rule "$aud" "attendees thread channel company explicit"
+[ -n "$proc" ] || bad "processor is required (<worker>/<skill>)"
+[ -z "$proc" ] || printf '%s' "$proc" | grep -Eq '^[a-z0-9-]+/[a-z0-9-]+$' || bad "processor must look like <worker>/<skill> (got '$proc')"
+oneof run "$run" "local cloud"
+if [ -z "$sched" ]; then bad "schedule is required (cron or on-close)"
+elif [ "$sched" != on-close ] && [ "$(printf '%s' "$sched" | awk '{print NF}')" -ne 5 ]; then bad "schedule must be a 5-field cron or on-close (got '$sched')"; fi
+
+[ "$v" -eq 0 ] && { echo "$f: ok"; exit 0; }
+exit 1

package/dist/command-catalog.generated.d.ts

@@ -1623,14 +1623,14 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "outbound";
-        readonly description: "List grants a source-company group holds on other companies";
+        readonly description: "List grants a source-company group holds on other companies; requires --group <groupId>.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options]";
         readonly arguments: readonly [];
         readonly options: readonly [{
             readonly flags: "--group <groupId>";
-            readonly description: "Group id to inspect";
+            readonly description: "Group id to inspect (required)";
         }];
         readonly subcommands: readonly [];
     }, {
@@ -5205,6 +5205,84 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "HQ installation to operate on";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "audience-grant";
+            readonly description: "Grant scoped ontology audiences and verify each grant";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "brief";
+            readonly description: "Render the local ontology company brief";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "candidate";
+            readonly description: "Write a deterministic ontology candidate";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "garden";
+            readonly description: "Promote local ontology candidates";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "source-worklist";
+            readonly description: "List unprocessed source items and their audience";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "source-yaml-validate";
+            readonly description: "Validate a source.yaml file";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[args...]";
+            readonly arguments: readonly [{
+                readonly name: "args";
+                readonly required: false;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
         }];
     }, {
         readonly name: "checkpoint-gate-setting";

package/dist/command-catalog.generated.js

@@ -2070,7 +2070,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "outbound",
-                "description": "List grants a source-company group holds on other companies",
+                "description": "List grants a source-company group holds on other companies; requires --group <groupId>.",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options]",
@@ -2078,7 +2078,7 @@ export const COMMAND_CATALOG = [
                 "options": [
                     {
                         "flags": "--group <groupId>",
-                        "description": "Group id to inspect"
+                        "description": "Group id to inspect (required)"
                     }
                 ],
                 "subcommands": []
@@ -6729,6 +6729,102 @@ export const COMMAND_CATALOG = [
                             }
                         ],
                         "subcommands": []
+                    },
+                    {
+                        "name": "audience-grant",
+                        "description": "Grant scoped ontology audiences and verify each grant",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "brief",
+                        "description": "Render the local ontology company brief",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "candidate",
+                        "description": "Write a deterministic ontology candidate",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "garden",
+                        "description": "Promote local ontology candidates",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "source-worklist",
+                        "description": "List unprocessed source items and their audience",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "source-yaml-validate",
+                        "description": "Validate a source.yaml file",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[args...]",
+                        "arguments": [
+                            {
+                                "name": "args",
+                                "required": false,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
                     }
                 ]
             },

package/dist/commands/auth.js

@@ -36,6 +36,44 @@ function decodeIdTokenClaims(idToken) {
         return undefined;
     }
 }
+function formatAuthExpiry(expiresAt, now = Date.now()) {
+    const expiresAtMs = typeof expiresAt === "number" ? expiresAt : Date.parse(expiresAt);
+    const expiresAtDate = new Date(expiresAtMs);
+    if (!Number.isFinite(expiresAtMs) || Number.isNaN(expiresAtDate.getTime())) {
+        return String(expiresAt);
+    }
+    const remainingMs = expiresAtMs - now;
+    const absoluteMs = Math.abs(remainingMs);
+    let unit;
+    let unitMs;
+    if (absoluteMs >= 365 * 24 * 60 * 60 * 1_000) {
+        unit = "year";
+        unitMs = 365 * 24 * 60 * 60 * 1_000;
+    }
+    else if (absoluteMs >= 30 * 24 * 60 * 60 * 1_000) {
+        unit = "month";
+        unitMs = 30 * 24 * 60 * 60 * 1_000;
+    }
+    else if (absoluteMs >= 24 * 60 * 60 * 1_000) {
+        unit = "day";
+        unitMs = 24 * 60 * 60 * 1_000;
+    }
+    else if (absoluteMs >= 60 * 60 * 1_000) {
+        unit = "hour";
+        unitMs = 60 * 60 * 1_000;
+    }
+    else if (absoluteMs >= 60 * 1_000) {
+        unit = "minute";
+        unitMs = 60 * 1_000;
+    }
+    else {
+        unit = "second";
+        unitMs = 1_000;
+    }
+    const relative = new Intl.RelativeTimeFormat("en", { numeric: "always" })
+        .format(Math.round(remainingMs / unitMs), unit);
+    return expiresAtDate.toISOString() + " (" + relative + ")";
+}
 function peekIdToken(idToken) {
     const claims = decodeIdTokenClaims(idToken);
     return {
@@ -201,8 +239,8 @@ export function registerAuthCommands(program) {
         const expiring = isExpiring(cached);
         const label = who ? `${who} — ` : "";
         console.log(expiring
-            ? chalk.yellow(`${label}HQ session cached but expiring (expiresAt=${cached.expiresAt})`)
-            : chalk.green(`${label}HQ session valid (expiresAt=${cached.expiresAt})`));
+            ? chalk.yellow(`${label}HQ session cached but expiring (expiresAt=${formatAuthExpiry(cached.expiresAt)})`)
+            : chalk.green(`${label}HQ session valid (expiresAt=${formatAuthExpiry(cached.expiresAt)})`));
         console.log(chalk.dim(`token source: ${tokenSource}`));
     });
 }

package/dist/commands/core-ontology-native.d.ts

@@ -0,0 +1,16 @@
+/** Native TypeScript implementation of the local ontology scaffold scripts. */
+import { Command } from "commander";
+export interface ScriptResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function preferenceValue(root: string, company: string, field: string): ScriptResult;
+export declare function sourceYamlValidate(file: string | undefined): ScriptResult;
+export declare function candidateCommand(args: string[], root: string): ScriptResult;
+export declare function briefCommand(args: string[], defaultRoot: string): ScriptResult;
+export declare function gardenCommand(args: string[], defaultRoot: string): ScriptResult;
+export declare function audienceGrant(args: string[], root: string): ScriptResult;
+export declare function worklistCommand(args: string[], root: string): ScriptResult;
+export declare function registerCoreOntologyNativeCommands(ontology: Command, rootFor: () => string): void;
+//# sourceMappingURL=core-ontology-native.d.ts.map