@ai-substrate/engineering-harness 0.2.0

package/harness/cli/dist/services/update/update-service.js

@@ -0,0 +1,91 @@
+import { readCache, writeCache } from './cache.js';
+import { UPDATE_COMMAND } from './constants.js';
+import { isNewer } from './semver.js';
+/** The throttle window: at most one registry lookup per 24h. */
+export const CHECK_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * Build the `update_available` field iff `latest` is strictly newer than
+ * `installed`. The command is pinned to "harness update" (AC7).
+ */
+export function toUpdateAvailable(installed, latest) {
+    if (!latest)
+        return null;
+    return isNewer(latest, installed) ? { installed, latest, command: UPDATE_COMMAND } : null;
+}
+/**
+ * SYNC banner source for the hot path (T007): read the cache and, if its
+ * last-known latest is newer than the installed version, return the notice.
+ * No network, a single cache read — safe to call on every command exit.
+ */
+export function bannerFromCache(fs, env, installed) {
+    const cache = readCache(fs, env);
+    return toUpdateAvailable(installed, cache?.latest ?? null);
+}
+/** Whether the cache is stale enough to warrant a fresh lookup. */
+export function isDue(now, lastSuccessIso, windowMs = CHECK_WINDOW_MS) {
+    const nowMs = Date.parse(now);
+    const lastMs = Date.parse(lastSuccessIso);
+    if (Number.isNaN(nowMs) || Number.isNaN(lastMs))
+        return true; // unreadable ts ⇒ due
+    const delta = nowMs - lastMs;
+    if (delta < 0)
+        return false; // clock went backwards ⇒ treat the cache as fresh
+    return delta >= windowMs;
+}
+/**
+ * Throttled update check. Reads the cache; if `force` or the 24h window has
+ * elapsed, does exactly ONE registry lookup. A successful lookup (non-null)
+ * advances the cache (ts + latest); a failed/empty lookup (null or throw) keeps
+ * the cache untouched so a previously-known update survives (AC9). When not due,
+ * reports off the last-known cache with no network call (AC5).
+ */
+export async function runCheck(deps, installed, opts) {
+    const { fs, env, clock, lookup } = deps;
+    const cache = readCache(fs, env);
+    const now = clock.nowIso();
+    const due = (opts?.force ?? false) || cache === null || isDue(now, cache.last_success_iso);
+    if (!due) {
+        const known = cache?.latest ?? null;
+        return {
+            installed,
+            latest: known,
+            update_available: toUpdateAvailable(installed, known),
+            checked: false,
+            refreshed: false,
+        };
+    }
+    let latest = null;
+    try {
+        latest = await lookup.latest();
+    }
+    catch {
+        latest = null;
+    }
+    if (latest !== null) {
+        // Best-effort persist: a cache write failure (read-only home, permission
+        // denied) must NOT turn a successful lookup into a thrown check (companion F003).
+        try {
+            writeCache(fs, env, { last_success_iso: now, latest });
+        }
+        catch {
+            // ignore — the check still returns its result; next run re-checks.
+        }
+        return {
+            installed,
+            latest,
+            update_available: toUpdateAvailable(installed, latest),
+            checked: true,
+            refreshed: true,
+        };
+    }
+    // Lookup failed/empty: keep the cache (don't advance ts); fall back to last-known.
+    const known = cache?.latest ?? null;
+    return {
+        installed,
+        latest: known,
+        update_available: toUpdateAvailable(installed, known),
+        checked: true,
+        refreshed: false,
+    };
+}
+//# sourceMappingURL=update-service.js.map

package/harness/cli/dist/services/update/update-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-service.js","sourceRoot":"","sources":["../../../src/services/update/update-service.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Read the CLI version from the shipped repo-root `package.json`. Kept out of
+ * `index.ts` (which stays free of `node:fs`) — this is a bootstrap concern, not
+ * business logic. npm always ships `package.json` in the tarball; from
+ * `harness/cli/dist/version.js` it is three levels up — a path that holds both
+ * in-repo and when installed via npx.
+ */
+export declare function readVersion(): string;

package/harness/cli/dist/version.js

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * Read the CLI version from the shipped repo-root `package.json`. Kept out of
+ * `index.ts` (which stays free of `node:fs`) — this is a bootstrap concern, not
+ * business logic. npm always ships `package.json` in the tarball; from
+ * `harness/cli/dist/version.js` it is three levels up — a path that holds both
+ * in-repo and when installed via npx.
+ */
+export function readVersion() {
+    const manifestUrl = new URL('../../../package.json', import.meta.url);
+    const manifest = JSON.parse(readFileSync(fileURLToPath(manifestUrl), 'utf8'));
+    return manifest.version;
+}
+//# sourceMappingURL=version.js.map

package/harness/cli/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAMzC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAoB,CAAC;IACjG,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ai-substrate/engineering-harness",
+  "version": "0.2.0",
+  "description": "Starter Harness CLI Core — the agent-friendly front door to this repo's engineering harness.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AI-Substrate/harness-engineering.git"
+  },
+  "bin": {
+    "harness": "./harness/cli/bin/harness.js",
+    "engh": "./harness/cli/bin/harness.js"
+  },
+  "exports": {
+    ".": "./harness/cli/dist/index.js",
+    "./contract": {
+      "types": "./harness/cli/dist/services/extensions/contract.d.ts",
+      "import": "./harness/cli/dist/services/extensions/contract.js",
+      "default": "./harness/cli/dist/services/extensions/contract.js"
+    }
+  },
+  "files": [
+    "harness/cli/bin",
+    "harness/cli/dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "gen:docs": "node scripts/gen-docs.mjs",
+    "check:docs": "npm run gen:docs && git diff --exit-code harness/cli/src/services/docs/docs-content.ts",
+    "build": "npm run gen:docs && tsc -p harness/cli/tsconfig.json",
+    "prepare": "npm run build",
+    "test": "cd harness/cli && vitest run --coverage",
+    "lint": "biome check harness/cli",
+    "format": "biome format --write harness/cli",
+    "fix": "biome check --write harness/cli"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "jiti": "2.7.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.8",
+    "dependency-cruiser": "^17.4.3",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  }
+}