@zortexhq/install 0.1.23

package/README.md

@@ -0,0 +1,127 @@
+# Zortex for Windows
+
+This package installs the Windows x64 Zortex CLI and its bundled Bun runtime.
+
+## Quick start
+
+**Requirements:** Windows x64, Node.js 18 or newer, and a local `codex`
+command on `PATH`. Install Zortex from npm:
+
+```powershell
+npm install --global @zortexhq/install
+```
+
+The preferred experience is to tell Codex to install and connect Zortex:
+
+> Install Zortex and connect my available apps.
+
+Codex runs the explicit, non-interactive route:
+
+```powershell
+zortex onboard --agent --host codex --json
+```
+
+The installer-owned Codex skill refreshes `@zortexhq/install@latest` before
+onboarding, so an old or stale `zortex` shim cannot silently keep an
+older release active.
+Its Bun runtime runs from a versioned copy under `%LOCALAPPDATA%\Zortex`, so a
+live local gateway does not lock the npm package directory during a later update.
+
+For a Zortex connection request, the installed skill uses this local CLI route
+instead of Codex's already-authenticated Gmail or Google Drive apps. Say
+explicitly that you want a built-in Codex app only when that is the intended
+connector.
+
+Onboarding automatically selects all released Windows recipes: Gmail, Google
+Drive, and Outlook. For an application outside that roster, inspect the
+installed connection recipes first:
+
+```powershell
+zortex autopilot recipes --json
+```
+
+The recipe aliases state whether Zortex has a released automatic route. If no recipe matches, use `zortex connect <kebab-id>` to
+file or join the existing connector-skill fabrication order; it is not a false
+claim that the unknown app is already connected. In a Codex-launched terminal,
+a bare `zortex` starts the same automatic agent onboarding.
+
+### What happens next
+
+1. Zortex checks the inherited Codex/Terminal Windows token. It does not ask
+   for broad elevation and does not use a model on the normal path.
+2. It records a reversible Autopilot receipt, configures its own read-only
+   Codex MCP bridge, and automatically starts the existing full sync for every
+   released source in the background. Users do not select sources or request
+   a preliminary sample.
+3. If a provider needs OAuth, Zortex opens the provider page itself. The user
+   completes only password entry, MFA, consent, CAPTCHA, hardware-key touch, or
+   account-risk confirmation in that provider surface. Zortex never asks the
+   user to run a shell command or paste a credential.
+4. The user may ask a question as soon as authorization is connected. Codex
+   checks the receipt while background synchronization runs:
+
+   ```powershell
+   zortex autopilot connect-status <receipt-id>
+   ```
+
+   The result includes each source's synchronized count and `backfill` state.
+   A scoped question uses matching synchronized data and reports incomplete
+   coverage if catch-up is still running. A question without a range waits for
+   `caught_up` and analyzes the complete connected corpus.
+5. Codex uses the read-only `indra.context` bridge and cites the returned
+   Zortex references.
+
+There is no ten-item onboarding sample. Full coverage is claimed only when a
+source reports `backfill: caught_up`.
+
+### Supported Windows Autopilot sources
+
+| Source | Sync target | Notes |
+| --- | --- | --- |
+| `gmail` | Full connected mailbox | Uses the existing read-only Gmail connector and its declared exclusions. |
+| `google-drive` | Full connected Drive corpus | Uses the existing read-only Drive connector and its declared exclusions. |
+| `outlook` | Full connected mailbox | Uses the unchanged 0.1.19/0.1.20 Outlook connector. |
+| `notion` | Connector fabrication | No released automatic authorization route yet; request files or joins a D29 build order. |
+| `posthog` | Connector fabrication | No released automatic authorization route yet; request files or joins a D29 build order. |
+| `whatsapp` | Deferred | Not part of this Windows Preview. |
+
+`chrome-history` and `computer-files` need a bounded user selection before
+Autopilot may read them. `github` is currently blocked by its clone-credential
+rail, and WeChat is deliberately excluded from this Windows release path.
+
+### Undo a connection
+
+To revoke the exact host grant and owned MCP configuration associated with a
+receipt, run:
+
+```powershell
+zortex autopilot connect-rollback <receipt-id>
+```
+
+This disables that connection; it does not claim to erase append-only local
+records. Use the product's audited privacy-erasure path for data deletion.
+
+### Troubleshooting
+
+- `NEEDS_ATTENTION`: let Codex inspect the receipt and perform its own bounded
+  repair. Do not paste a credential or run a repair command yourself.
+- `codex` not found: install/start the local Codex CLI first, then rerun the
+  explicit onboarding command.
+- Incomplete all-data answer: wait for each requested source to report
+  `backfill: caught_up`.
+
+When Codex invokes the npm launcher with no command, it starts
+`zortex onboard --agent --host codex`. That scripted onboarding first proves
+what the inherited Codex/Terminal Windows token can access; it does not open a
+broad permission prompt or call a model. Only a real source-specific access,
+UAC, or provider boundary becomes a typed `NEEDS_ATTENTION` item. Connector
+workers inherit that same host token; they do not use MCP as a permission or
+execution channel.
+
+After installation/onboarding, Zortex provides a local, read-only MCP context
+gateway. Connectors do not depend on MCP: Autopilot runs from the onboarding CLI
+and records its own reversible receipts. A signed local content pack can be
+installed with `zortex bootstrap --pack <pack.indrapack>`; that command adds
+only its owned Codex MCP entry and Skill, and leaves pack skills as unexecuted
+candidates. It does not install a local model, send user data to a provider, or
+enable action tools.

package/bin/zortex.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { copyFileSync, existsSync, mkdirSync, statSync } = require("node:fs");
+const { homedir } = require("node:os");
+const { delimiter, join } = require("node:path");
+
+const ROOT = join(__dirname, "..");
+const BUNDLE = join(ROOT, "dist", "zortex.js");
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function bunPath(appRoot) {
+  let bundled;
+  try {
+    bundled = require.resolve("@oven/bun-windows-x64/bin/bun.exe");
+  } catch {
+    // Optional platform runtime absent: an existing Bun installation is still valid.
+  }
+  if (bundled !== undefined) {
+    const version = require(join(ROOT, "package.json")).optionalDependencies["@oven/bun-windows-x64"];
+    if (typeof version !== "string" || !/^[A-Za-z0-9._-]+$/.test(version)) throw new Error("bundled Bun runtime version is invalid");
+    const runtime = join(appRoot, "runtime", `bun-${version}.exe`);
+    if (!isFile(runtime)) {
+      mkdirSync(join(appRoot, "runtime"), { recursive: true });
+      copyFileSync(bundled, runtime);
+    }
+    return runtime;
+  }
+  const executable = "bun.exe";
+  for (const directory of (process.env.PATH || "").split(delimiter)) {
+    const candidate = join(directory, executable);
+    if (directory && isFile(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function hasAppRoot(args) {
+  return args.some((arg, index) => arg === "--app-root" ? args[index + 1] !== undefined : arg.startsWith("--app-root="));
+}
+
+/** A no-argument npm invocation is the start of onboarding. Codex exposes a
+ * stable session/thread marker to its child processes, so it can use the
+ * noninteractive agent flow while an ordinary terminal keeps the human flow. */
+function defaultInvocationArgs(args, env = process.env) {
+  if (args.length > 0) return args;
+  return env.CODEX_SESSION_ID || env.CODEX_THREAD_ID
+    ? ["onboard", "--agent", "--host", "codex"]
+    : ["onboard"];
+}
+
+function main() {
+  if (!isFile(BUNDLE)) {
+    process.stderr.write("zortex: packaged bundle is missing; reinstall @zortexhq/install\n");
+    return 1;
+  }
+  const appRoot = process.env.ZORTEX_APP_ROOT || join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "Zortex");
+  let bun;
+  try {
+    bun = bunPath(appRoot);
+  } catch (error) {
+    process.stderr.write(`zortex: could not prepare the package-owned Bun runtime: ${error.message}\n`);
+    return 1;
+  }
+  if (bun === undefined) {
+    process.stderr.write("zortex: no Bun runtime found; reinstall @zortexhq/install without omitting optional dependencies\n");
+    return 1;
+  }
+  const args = defaultInvocationArgs(process.argv.slice(2));
+  const forwarded = hasAppRoot(args) ? args : ["--app-root", appRoot, ...args];
+  const child = spawnSync(bun, [BUNDLE, ...forwarded], { stdio: "inherit", env: process.env });
+  if (child.error) {
+    process.stderr.write(`zortex: could not start Bun: ${child.error.message}\n`);
+    return 1;
+  }
+  return child.status === null ? 1 : child.status;
+}
+
+module.exports = { defaultInvocationArgs };
+
+if (require.main === module) process.exitCode = main();