iterate 0.2.6 → 0.3.0

package/README.md

@@ -1,97 +1,107 @@
 # iterate
 
-CLI for Iterate.
+CLI for OS Next (`apps/os-next`). Requires Node >=22.15; no Bun runtime.
 
-`npx iterate` opens the Iterate chat terminal UI. It is equivalent to
-`npx iterate chat`.
-
-The package also runs as a thin bootstrapper: inside this repo it delegates to
-the local `packages/iterate` source, and from npm it runs the published build.
+```sh
+npx iterate                       # offline help
+npx iterate login                 # browser OAuth with project consent
+npx iterate projects list
+npx iterate orgs list
+npx iterate ping
+npx iterate repl --project my-project   # local Node REPL
+npx iterate itx run --project my-project --eval 'return await itx.whoami();'
+npx iterate use-my-computer --project my-project --name myComputer
+npx iterate menubar --project my-project   # macOS app
+npx iterate logout
+```
 
-## Requirements
+The default server is `https://os.iterate2.com`. Login uses that server's OAuth
+issuer, PKCE and a loopback callback. Tokens refresh automatically before a
+command when close to expiry. `ITERATE_BEARER_TOKEN` supplies a token for scripts;
+`APP_CONFIG_ADMIN_API_SECRET` supplies operator credentials and takes precedence.
+`ITERATE_SKIP_BROWSER_OPEN=1` prints the login URL without opening a browser.
+
+## Running scripts
+
+`itx run` executes a JavaScript function body on OS Next with `itx` in scope.
+Use `return` for the result. The server records the run and its settlement;
+the CLI never retries a script automatically. Scripts execute on the server,
+so local Node APIs and local filesystem access are unavailable.
+
+```sh
+iterate itx run --project my-project --context /notes --eval '
+  await itx.append({ type: "note", payload: { text: "hello" } });
+  return await itx.readEvents(0, 10);
+'
+iterate itx run --project my-project --file ./script.js
+cat script.js | iterate itx run --project my-project --file -
+```
 
-- Node `>=22`
-- Bun, for the current OpenTUI-based chat terminal runtime
+Specify exactly one of `--eval` or `--file`. `--context` is a project-local path
+(default `/`). `--project` accepts an id or slug; otherwise the CLI uses the
+config's `defaultProject`, or the only project accessible to the session.
 
-## Quick start
+## Use my computer
 
-Run without installing globally:
+`use-my-computer` shares a Mac as a live OS Next capability until Ctrl-C:
 
-```bash
-npx iterate
-```
+- `itx.myComputer.ask({ question, buttons? })`: native choice dialog.
+- `itx.myComputer.notify({ message, title? })`: desktop notification.
+- `itx.myComputer.runSwift({ code })`: Swift with the owner's local permissions.
+- `itx.myComputer.__describe()`: usage instructions and method signatures.
 
-If you are not logged in yet, `iterate chat` starts the browser OAuth flow. The
-auth flow asks for project access and can create your first organization and
-project before returning to the CLI.
+The command requires macOS, AppleScript and Swift. Share only with a project
+you trust: its callers can run local code. The capability belongs to the live
+connection and is released on exit. A disconnect or token expiry ends sharing
+with an error; rerun the command to refresh authentication and reconnect.
 
-```bash
-npx iterate chat
-```
+## Configs and migration
 
-For help and other commands:
+Configs live in `${XDG_CONFIG_HOME:-~/.config}/iterate/config.json`. Selection
+order is `--config`, a parent-directory workspace mapping, the default config,
+a single saved config, then built-in `prd`.
 
-```bash
-npx iterate --help
-npx iterate login
-npx iterate orgs list
-npx iterate config list
+```sh
+iterate config set --name next --os-base-url https://os.iterate2.com \
+  --default-project my-project --set-default
+iterate --config next login
+iterate config set --name local --os-base-url http://localhost:8787 --set-workspace
+iterate config list
+iterate config get
 ```
 
-## Commands
-
-- `iterate` - open chat
-- `iterate chat` - open the Iterate agent chat terminal UI
-- `iterate login` - authenticate with browser-based OAuth
-- `iterate logout` - remove the stored session for the current config
-- `iterate orgs list`
-- `iterate config ...`
-- `iterate os ...`
-
-## Config file
-
-Config path:
-
-`${XDG_CONFIG_HOME:-~/.config}/iterate/config.json`
-
-Config shape:
-
-```json
-{
-  "configs": {
-    "default": {
-      "osBaseUrl": "https://os.iterate.com",
-      "authBaseUrl": "https://auth.iterate.com",
-      "defaultProject": "my-project"
-    },
-    "dev": {
-      "osBaseUrl": "http://localhost:54896",
-      "authBaseUrl": "http://localhost:7101"
-    }
-  },
-  "default": "default",
-  "workspaces": {
-    "/absolute/workspace/path": "dev"
-  }
-}
-```
+Existing configs keep their server URL. For a config that targets the old OS,
+set its `--os-base-url` to an OS Next deployment and log in again. Changing the
+server clears that config's session. There is no separate `authBaseUrl` setting.
 
-Config resolution priority: `--config` flag > workspace match (walk up from cwd) > `default` key > single-config auto-select.
+The old chat TUI and remotely discovered `iterate os ...` commands are removed.
+The menu bar supports sign-in and computer sharing. Approval code is retained
+but dormant until OS Next supports it. Use `iterate itx run` for scripts;
+its `--project` selects the project and `--context` selects a path within it.
 
-## Local iterate dev
+## Node REPL
 
-If you run inside an `iterate/iterate` clone, the CLI auto-detects it and
-delegates to the local source instead of the published build.
+`iterate repl` opens a local Node REPL with the authenticated session as `itx`
+(try `await itx.projects.list()`) and the transport's `RpcTarget` constructor.
+Pass `--project my-project --context /` to bind `itx` to a project context;
+a configured `defaultProject` also selects a project. Top-level `await`, Node APIs and `.load` are available. The bindings remain available after `.clear`; `.exit` releases the context and connection. A lost connection
+ends the REPL visibly; it never silently repeats your commands.
 
-## Publishing (maintainers)
+## Node connections
 
-From repo root:
+`iterate/next/node` exposes a connection owner for OS Next scripts and live
+providers. It uses the same protocol and cleanup as the CLI:
 
-```bash
-pnpm --filter ./packages/iterate build
-pnpm --filter ./packages/iterate typecheck
-pnpm --filter ./packages/iterate test
-pnpm exec oxlint packages/iterate/src/cli.ts packages/iterate/src/cli.test.ts
-pnpm exec oxfmt --check packages/iterate
-pnpm --filter ./packages/iterate publish --access public
+```js
+import { connectOsNext } from "iterate/next/node";
+
+using connection = await connectOsNext({
+  baseUrl: "https://os.iterate2.com",
+  auth: { type: "bearer", token: process.env.ITERATE_BEARER_TOKEN },
+});
+using project = await connection.session.projects.get("my-project");
+console.log(await project.run("async (itx) => await itx.whoami()"));
 ```
+
+The package launcher delegates to repository source during development and
+uses the published build when installed through `npx`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,55 @@
+# Third-party notices
+
+`dist/document-review.mjs` bundles the following third-party software.
+
+## Roughdraft 0.1.10
+
+- Source: https://github.com/Lex-Inc/roughdraft
+- Author: Nathan Baschez
+- License: MIT, as declared by Roughdraft's published package manifest and source README.
+
+The Roughdraft source tree and published package manifest do not include a copyright notice. The MIT license text is reproduced below without adding one.
+
+```text
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## yaml 2.9.0
+
+- Source: https://github.com/eemeli/yaml/tree/v2.9.0
+- Author: Eemeli Aro <eemeli@gmail.com>
+- License: ISC
+
+```text
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+```

package/bin/iterate.js

@@ -28,6 +28,18 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkgRoot = dirname(__dirname);
 
+// `npx iterate` and `bunx iterate` should exercise the package that the runner
+// just installed. Normal installed/global executions still delegate to local
+// repo source below, which keeps monorepo development fast.
+const isEphemeralPackageRunner = () =>
+  process.env.npm_command === "exec" &&
+  (process.env.npm_lifecycle_event === "npx" || process.env.npm_lifecycle_event === "bunx");
+
+// The black-box PTY lane builds the package, then exercises this same public
+// bin while the monorepo source tree is still present. Force the published
+// artifact path so that test cannot accidentally fall back to TypeScript.
+const forceBuiltPackage = process.env.ITERATE_FORCE_BUILT_PACKAGE === "1";
+
 /**
  * Find a local version of the iterate CLI that differs from the currently
  * running script. Returns an importable module path, or null.
@@ -53,7 +65,10 @@ const findLocalModule = () => {
   // 2. Check for a local node_modules install
   const nmRoot = findUp("node_modules/.bin/iterate");
   if (nmRoot) {
-    const nmScript = join(nmRoot, "node_modules/.bin/iterate");
+    // pnpm's .bin entry is a shell shim, so compare the package's actual bin.
+    // Comparing the shim itself mistakes our own package for another install
+    // and sends repository development to a stale dist build.
+    const nmScript = join(nmRoot, "node_modules/iterate/bin/iterate.js");
     if (existsSync(nmScript) && realpathSync(nmScript) !== selfReal) {
       // Published package — use dist
       const nmDist = join(nmRoot, "node_modules/iterate/dist/index.mjs");
@@ -64,7 +79,7 @@ const findLocalModule = () => {
   return null;
 };
 
-const localModule = findLocalModule();
+const localModule = isEphemeralPackageRunner() || forceBuiltPackage ? null : findLocalModule();
 if (localModule) {
   const { runCli } = await import(localModule);
   await runCli();
@@ -73,7 +88,7 @@ if (localModule) {
   // In monorepo dev: src/index.ts exists. Published: dist/index.mjs exists.
   const srcPath = join(pkgRoot, "src/index.ts");
   const distPath = join(pkgRoot, "dist/index.mjs");
-  const modulePath = existsSync(srcPath) ? srcPath : distPath;
+  const modulePath = !forceBuiltPackage && existsSync(srcPath) ? srcPath : distPath;
   const { runCli } = await import(modulePath);
   await runCli();
 }

package/dist/api-url-B6404M82.mjs

@@ -0,0 +1,17 @@
+//#region src/itx/api-url.ts
+/**
+* An OS deployment's `/api` WebSocket URL from its http(s) base — the ONE
+* place that knows the path and the ws/wss protocol swap, shared by the
+* shared session and the one-shot Node client.
+*/
+function apiWebSocketUrl(baseUrl) {
+	const base = baseUrl.trim().replace(/\/+$/, "");
+	if (!base) throw new Error("an OS deployment base URL is required (the config's APP_CONFIG_BASE_URL)");
+	const url = new URL("/api", base);
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	return url;
+}
+//#endregion
+export { apiWebSocketUrl as t };
+
+//# sourceMappingURL=api-url-B6404M82.mjs.map

package/dist/api-url-B6404M82.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-url-B6404M82.mjs","names":[],"sources":["../src/itx/api-url.ts"],"sourcesContent":["/**\n * An OS deployment's `/api` WebSocket URL from its http(s) base — the ONE\n * place that knows the path and the ws/wss protocol swap, shared by the\n * shared session and the one-shot Node client.\n */\nexport function apiWebSocketUrl(baseUrl: string): URL {\n  const base = baseUrl.trim().replace(/\\/+$/, \"\");\n  if (!base) {\n    throw new Error(\"an OS deployment base URL is required (the config's APP_CONFIG_BASE_URL)\");\n  }\n  const url = new URL(\"/api\", base);\n  url.protocol = url.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n  return url;\n}\n"],"mappings":";;;;;;AAKA,SAAgB,gBAAgB,SAAsB;CACpD,MAAM,OAAO,QAAQ,KAAK,CAAC,CAAC,QAAQ,QAAQ,EAAE;CAC9C,IAAI,CAAC,MACH,MAAM,IAAI,MAAM,0EAA0E;CAE5F,MAAM,MAAM,IAAI,IAAI,QAAQ,IAAI;CAChC,IAAI,WAAW,IAAI,aAAa,WAAW,SAAS;CACpD,OAAO;AACT"}

package/dist/app-ref-BipL0feU.mjs

@@ -0,0 +1,35 @@
+//#region src/starter-apps/guestbook/app-ref.ts
+const guestbookStreamPath = "/guestbook";
+const guestbookWorkerRef = {
+	className: "GuestbookApp",
+	durableWorkerKey: "app-guestbook-stream",
+	path: "/",
+	source: { createWorker: {
+		entryPoint: "node_modules/iterate/dist/starter-apps/guestbook/configured-worker.mjs",
+		files: {
+			include: ["package.json"],
+			repoPath: "/repos/config",
+			type: "repo"
+		}
+	} },
+	type: "stateful"
+};
+/**
+* The Guestbook's creation facts. The project worker owns committed event
+* delivery through GuestbookApp.processEvent; no stream ever carries an
+* app-specific subscription for the Guestbook (streams that predate the
+* current subscription model are recreated, not migrated), so there is no
+* retirement fact to append — removing a key that was never configured is a
+* hard error.
+*/
+function guestbookCreationEvents() {
+	return [{
+		type: "events.iterate.com/guestbook/created",
+		payload: { config: { title: "Guestbook" } },
+		idempotencyKey: "guestbook/created"
+	}];
+}
+//#endregion
+export { guestbookStreamPath as n, guestbookWorkerRef as r, guestbookCreationEvents as t };
+
+//# sourceMappingURL=app-ref-BipL0feU.mjs.map

package/dist/app-ref-BipL0feU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-ref-BipL0feU.mjs","names":[],"sources":["../src/starter-apps/guestbook/app-ref.ts"],"sourcesContent":["// The Guestbook's physical identity. Keeping the durable key stable preserves\n// its processor storage while the implementation moves out of config repos.\nimport type { StreamEventInput } from \"../../processors/index.ts\";\nimport type { StatefulDynamicWorkerRef } from \"../../sdk.ts\";\n\nexport const guestbookStreamPath = \"/guestbook\";\n\nexport const guestbookWorkerRef = {\n  className: \"GuestbookApp\",\n  // \"-stream\" keeps clear of a retired predecessor's durable identity.\n  durableWorkerKey: \"app-guestbook-stream\",\n  path: \"/\",\n  source: {\n    createWorker: {\n      entryPoint: \"node_modules/iterate/dist/starter-apps/guestbook/configured-worker.mjs\",\n      files: {\n        include: [\"package.json\"],\n        repoPath: \"/repos/config\",\n        type: \"repo\",\n      },\n    },\n  },\n  type: \"stateful\",\n} satisfies StatefulDynamicWorkerRef;\n\n/**\n * The Guestbook's creation facts. The project worker owns committed event\n * delivery through GuestbookApp.processEvent; no stream ever carries an\n * app-specific subscription for the Guestbook (streams that predate the\n * current subscription model are recreated, not migrated), so there is no\n * retirement fact to append — removing a key that was never configured is a\n * hard error.\n */\nexport function guestbookCreationEvents(): StreamEventInput[] {\n  return [\n    {\n      type: \"events.iterate.com/guestbook/created\",\n      payload: { config: { title: \"Guestbook\" } },\n      idempotencyKey: \"guestbook/created\",\n    },\n  ];\n}\n"],"mappings":";AAKA,MAAa,sBAAsB;AAEnC,MAAa,qBAAqB;CAChC,WAAW;CAEX,kBAAkB;CAClB,MAAM;CACN,QAAQ,EACN,cAAc;EACZ,YAAY;EACZ,OAAO;GACL,SAAS,CAAC,cAAc;GACxB,UAAU;GACV,MAAM;EACR;CACF,EACF;CACA,MAAM;AACR;;;;;;;;;AAUA,SAAgB,0BAA8C;CAC5D,OAAO,CACL;EACE,MAAM;EACN,SAAS,EAAE,QAAQ,EAAE,OAAO,YAAY,EAAE;EAC1C,gBAAgB;CAClB,CACF;AACF"}

package/dist/app-ref-C1CrgXqX.mjs

@@ -0,0 +1,7 @@
+import { notesWorkerRef as notesWorkerRef$1 } from "./starter-apps/notes/ref.mjs";
+//#region src/starter-apps/notes/app-ref.ts
+const notesWorkerRef = notesWorkerRef$1;
+//#endregion
+export { notesWorkerRef as t };
+
+//# sourceMappingURL=app-ref-C1CrgXqX.mjs.map

package/dist/app-ref-C1CrgXqX.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-ref-C1CrgXqX.mjs","names":["notesWorkerRefLiteral"],"sources":["../src/starter-apps/notes/app-ref.ts"],"sourcesContent":["// The NotesApp's physical identity: a stable durable key preserves its\n// processor storage across implementation updates. The literal lives in\n// ref.ts (dependency-free for the mobile app); this module holds the\n// satisfies check against the real ref type.\nimport type { StatefulDynamicWorkerRef } from \"../../sdk.ts\";\nimport { notesWorkerRef as notesWorkerRefLiteral } from \"./ref.ts\";\n\nexport { notesRepoPath, notesWorkspacePath } from \"./ref.ts\";\n\nexport const notesWorkerRef = notesWorkerRefLiteral satisfies StatefulDynamicWorkerRef;\n"],"mappings":";;AASA,MAAa,iBAAiBA"}

package/dist/app-ref-DYai_om1.mjs

@@ -0,0 +1,7 @@
+import { mediaWorkerRef as mediaWorkerRef$1 } from "./starter-apps/media/ref.mjs";
+//#region src/starter-apps/media/app-ref.ts
+const mediaWorkerRef = mediaWorkerRef$1;
+//#endregion
+export { mediaWorkerRef as t };
+
+//# sourceMappingURL=app-ref-DYai_om1.mjs.map

package/dist/app-ref-DYai_om1.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-ref-DYai_om1.mjs","names":["mediaWorkerRefLiteral"],"sources":["../src/starter-apps/media/app-ref.ts"],"sourcesContent":["// The MediaApp's physical identity: a stable durable key preserves its\n// processor storage across implementation updates. The literal lives in\n// ref.ts (dependency-free for the mobile e2e); this module holds the\n// satisfies check against the real ref type.\nimport type { StatefulDynamicWorkerRef } from \"../../sdk.ts\";\nimport { mediaWorkerRef as mediaWorkerRefLiteral } from \"./ref.ts\";\n\nexport { mediaStreamPath } from \"./ref.ts\";\n\nexport const mediaWorkerRef = mediaWorkerRefLiteral satisfies StatefulDynamicWorkerRef;\n"],"mappings":";;AASA,MAAa,iBAAiBA"}