@abstractframework/continuum 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laurent-Philippe Albou
+
+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.

package/README.md

@@ -0,0 +1,112 @@
+# AbstractContinuum
+
+Continuous iterative development and deployment console for AbstractFramework.
+
+Connect it to a Run Gateway and it becomes the framework's development
+cockpit (board-first, kanban/scrum-inspired — see
+[docs/design/redesign_2026_07.md](docs/design/redesign_2026_07.md)):
+
+- **Board** (landing page) — the work flow as a kanban: Triage → Ready →
+  In Progress → In Review → Done, with a Failed history lane. Cards carry
+  type / priority (P0–P3) / labels (sprints ride the `sprint-N` label
+  convention) / package chips and a Definition-of-Ready dot; the card
+  drawer holds the spec (view/edit + metadata), the item's runs, and the
+  QA review (acceptance-criteria checklist → promote / iterate / UAT).
+- **Executions** — the live ops view: queued / running / awaiting-QA
+  requests with live log tails (cursor-follow), one-click QA actions, and
+  a recently-finished strip.
+- **Backlog** — the full catalog power view (all kinds incl. recurrent /
+  deprecated / trash, search, batch execute, merge, AI assist + advisor).
+- **Agents & Entities** — the workforce: the configured execution agent
+  (executor is a pluggable seam — Codex CLI today), the advisor agent, a
+  track record from execution history, and gateway entities with their
+  skills.
+- **Team** — an [agora](docs/configuration.md#team-page-agora-hub) hub
+  client for human + agent collaboration: channels and DMs with threaded
+  messages, a unified inbox of open asks, hub-wide search, channel files,
+  work claims, and live updates over WebSocket. It posts as one configured
+  operator seat through a server-side proxy (the seat key never reaches the
+  browser).
+- **Inbox** — triage bug reports, feature requests, and email; run triage
+  and apply decisions.
+- **Services** — control managed prod/UAT processes (start / stop /
+  restart / redeploy) and write-only environment variables. This surface is
+  high trust: see [SECURITY.md](SECURITY.md) before exposing it.
+- **Settings** — gateway session sign-in and AI preferences.
+
+Executing a Ready item is gated by an advisory **Definition of Ready**
+checklist (type, real summary, acceptance criteria, test commands — parsed
+from the spec, override always available and labeled); promoting from
+review shows the acceptance criteria as a **Definition of Done** checklist.
+
+The observer app ([AbstractObserver](https://github.com/lpalbou/AbstractObserver))
+watches and discusses the running system; this app develops and deploys it.
+The pipeline is executor-agnostic by design: the gateway currently runs
+executions through the Codex CLI, but the executing agent is a pluggable
+seam and the UI reads the executor identity from the gateway's exec config
+(see [docs/architecture.md](docs/architecture.md)).
+
+## Install and run
+
+Requires Node.js ≥ 18 and a running Run Gateway
+([AbstractGateway](https://github.com/lpalbou/AbstractGateway), default
+`http://127.0.0.1:8080`).
+
+```bash
+npx @abstractframework/continuum
+# or install the CLI globally
+npm install -g @abstractframework/continuum
+abstractcontinuum
+```
+
+Open `http://localhost:3002` and sign in with a gateway user and token (the
+connection badge at the bottom of the sidebar). The token is exchanged
+server-side for an HttpOnly session cookie and never stored in the browser.
+
+Common environment variables (full list in
+[docs/configuration.md](docs/configuration.md), or `abstractcontinuum --help`):
+
+- `PORT` (default `3002`), `HOST` (default `127.0.0.1`)
+- `ABSTRACTCONTINUUM_GATEWAY_URL` (or `ABSTRACTGATEWAY_URL`) — the gateway
+  this deployment talks to (default `http://127.0.0.1:8080`)
+- `ABSTRACTCONTINUUM_HUB_URL` / `ABSTRACTCONTINUUM_HUB_SEAT` — the agora hub
+  and operator seat for the Team page
+
+Before exposing the console beyond localhost, read
+[docs/security.md](docs/security.md): a signed-in user can redeploy services.
+
+## Develop from source
+
+The source build resolves the shared UI kit (`@abstractframework/ui-kit`,
+`@abstractframework/panel-chat`) and the session proxy
+(`@abstractframework/app-server`) from a sibling
+[AbstractUIC](https://github.com/lpalbou/AbstractUIC) checkout:
+
+```bash
+git clone https://github.com/lpalbou/AbstractUIC.git abstractuic
+git clone https://github.com/lpalbou/AbstractContinuum.git abstractcontinuum
+cd abstractcontinuum
+npm install
+npm run dev        # vite dev server on :3003 (proxies /api to :8080)
+npm test           # vitest (unit + jsdom component tests)
+npm run build      # production build into dist/
+npm start          # serve dist/ + the app-origin gateway session proxy on :3002
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
+
+## Documentation
+
+- [docs/README.md](docs/README.md) — documentation index
+- [docs/getting-started.md](docs/getting-started.md) — first run and first execution
+- [docs/architecture.md](docs/architecture.md) — components, data flow, design boundaries
+- [docs/api.md](docs/api.md) — the gateway API families this app consumes
+- [docs/configuration.md](docs/configuration.md) — environment variables and settings
+- [docs/security.md](docs/security.md) — trust model (read before deploying)
+- [docs/faq.md](docs/faq.md) / [docs/troubleshooting.md](docs/troubleshooting.md)
+- [CHANGELOG.md](CHANGELOG.md) — release history
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development workflow
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/cli.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for AbstractContinuum
+ * Serves the built console and proxies /api/* to the gateway through the
+ * shared app-origin session proxy (first-party cookies + CSRF; tokens never
+ * in URLs) — the same @abstractframework/app-server module the observer,
+ * flow, and code apps converge on.
+ */
+
+import * as http from 'http';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join, extname, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createGatewaySessionProxy } from '@abstractframework/app-server';
+import { createHubProxy } from './hub_proxy.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DIST_DIR = join(__dirname, '..', 'dist');
+
+const argv = process.argv.slice(2);
+if (argv.includes('--version') || argv.includes('-v')) {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`Usage: abstractcontinuum [--help] [--version]
+
+Serves the AbstractContinuum console and proxies /api/* to a Run Gateway
+through a same-origin session proxy. Configuration is environment-driven:
+
+  PORT                            HTTP port (default 3002)
+  HOST                            bind address (default 127.0.0.1)
+  ABSTRACTCONTINUUM_GATEWAY_URL   gateway URL (fallback ABSTRACTGATEWAY_URL,
+                                  default http://127.0.0.1:8080)
+  ABSTRACTCONTINUUM_HUB_URL       agora hub for the Team page (fallback
+                                  AGORA_HUB_URL, default http://127.0.0.1:8765)
+  ABSTRACTCONTINUUM_HUB_SEAT      hub seat the Team page acts as (default laurent)
+  ABSTRACTCONTINUUM_HUB_KEYS      hub key store (default ~/.agora/keys.json)
+  ABSTRACTCONTINUUM_HUB_KEY       hub API key (overrides the key store)
+
+Documentation: https://github.com/lpalbou/AbstractContinuum#readme`);
+  process.exit(0);
+}
+
+const PORT = process.env.PORT || 3002;
+// Default bind is LOOPBACK (entity's c1768 SSRF finding against the shared
+// session proxy, plus a continuum-specific amplifier: this server also
+// mounts the hub proxy carrying the OPERATOR's seat key — a LAN peer
+// reaching the port could author hub messages as the operator). Wider
+// binds are an explicit deployment choice via HOST.
+const HOST = process.env.HOST || '127.0.0.1';
+const DEFAULT_GATEWAY_URL = String(process.env.ABSTRACTCONTINUUM_GATEWAY_URL || process.env.ABSTRACTGATEWAY_URL || 'http://127.0.0.1:8080').trim().replace(/\/+$/, '') || 'http://127.0.0.1:8080';
+const HUB_URL = String(process.env.ABSTRACTCONTINUUM_HUB_URL || process.env.AGORA_HUB_URL || 'http://127.0.0.1:8765').trim().replace(/\/+$/, '');
+const HUB_SEAT = String(process.env.ABSTRACTCONTINUUM_HUB_SEAT || 'laurent').trim();
+const HUB_KEYS_PATH = String(process.env.ABSTRACTCONTINUUM_HUB_KEYS || join(homedir(), '.agora', 'keys.json'));
+
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.webmanifest': 'application/manifest+json',
+};
+
+function getMimeType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+// Content-Security-Policy for the app document (security adversary P1
+// 2026-07-16): untrusted markdown (channel files, messages, attachments)
+// renders in this app, and standard markdown allows remote images — a
+// crafted ![](https://attacker/beacon.png) would beacon the operator's IP
+// and read-timing to an external host the moment a preview opens. img-src
+// 'self' data: kills that class app-wide. script-src 'self' is a backstop
+// belt (the renderer already cannot emit script). ws:/wss: are needed
+// because 'self' does not reliably cover scheme-different WebSocket dials;
+// only our own bundle can open sockets (script-src), so this stays tight.
+const CSP = [
+  "default-src 'self'",
+  "script-src 'self'",
+  "style-src 'self' 'unsafe-inline'", // React style={} attributes
+  "img-src 'self' data:",
+  "font-src 'self' data:",
+  "connect-src 'self' ws: wss:",
+  "object-src 'none'",
+  "base-uri 'self'",
+  "form-action 'self'",
+  "frame-ancestors 'none'",
+].join('; ');
+
+function serveFile(res, filePath) {
+  try {
+    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+      return false;
+    }
+    const content = readFileSync(filePath);
+    const mime = getMimeType(filePath);
+    const headers = {
+      'Content-Type': mime,
+      'Cache-Control': 'no-cache',
+      'X-Content-Type-Options': 'nosniff',
+    };
+    // CSP is a document policy — attach it where a document loads.
+    if (mime === 'text/html') headers['Content-Security-Policy'] = CSP;
+    res.writeHead(200, headers);
+    res.end(content);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Cookies abstractcontinuum_gateway_*, header x-abstractcontinuum-csrf, and
+// the ABSTRACTCONTINUUM_* / ABSTRACTGATEWAY_* env gates all derive from appId.
+const gatewaySessionProxy = createGatewaySessionProxy({
+  appId: 'abstractcontinuum',
+  defaultGatewayUrl: DEFAULT_GATEWAY_URL,
+});
+
+// Team page transport: /api/hub/* forwards an allowlisted hub API subset
+// with the OPERATOR seat's key attached server-side (proposal c1692,
+// agency contract c1696 — authorship stays the operator's own).
+const hubProxy = createHubProxy({ hubUrl: HUB_URL, seat: HUB_SEAT, keysPath: HUB_KEYS_PATH });
+
+const server = http.createServer((req, res) => {
+  // Parse against a FIXED base: a malformed Host header (e.g. "a b") makes
+  // new URL throw synchronously, which would kill the whole process from
+  // one bad request (adversarial P1 2026-07-13). The host plays no role in
+  // routing here — only the pathname does.
+  let pathname = '/';
+  let search = '';
+  try {
+    const u = new URL(req.url, 'http://local');
+    pathname = u.pathname;
+    search = u.search;
+  } catch {
+    res.writeHead(400);
+    res.end('Bad Request');
+    return;
+  }
+
+  if (hubProxy.handle(req, res, pathname, search)) {
+    return;
+  }
+
+  if (gatewaySessionProxy.handle(req, res, pathname)) {
+    return;
+  }
+
+  if (pathname.includes('..')) {
+    res.writeHead(400);
+    res.end('Bad Request');
+    return;
+  }
+
+  if (pathname === '/' || pathname === '') {
+    pathname = '/index.html';
+  }
+
+  const filePath = join(DIST_DIR, pathname);
+  if (serveFile(res, filePath)) return;
+  if (serveFile(res, filePath + '.html')) return;
+
+  // SPA fallback
+  if (serveFile(res, join(DIST_DIR, 'index.html'))) return;
+
+  res.writeHead(404);
+  res.end('Not Found');
+});
+
+// Live hub updates: relay browser WebSockets to the hub with the seat key
+// attached server-side (operator c2240 — realtime, not 5s polling).
+server.on('upgrade', (req, socket, head) => {
+  // F7 (dm-99 tail): a raw upgrade socket with no 'error' listener is a
+  // process-killer (browser aborts mid-handshake raise uncaught 'error');
+  // and a rejected relay promise without .catch is an unhandled rejection.
+  socket.on('error', () => {
+    try { socket.destroy(); } catch { /* already gone */ }
+  });
+  void hubProxy.handleUpgrade(req, socket, head).then((handled) => {
+    if (!handled) socket.destroy();
+  }).catch(() => {
+    try { socket.destroy(); } catch { /* already gone */ }
+  });
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`
+AbstractContinuum is running.
+  Local:   http://localhost:${PORT}
+  Gateway: ${DEFAULT_GATEWAY_URL}
+`);
+});
+
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));