@milpa/comal 0.1.0 → 0.1.2

package/README.md

@@ -1,82 +1,84 @@
-# Instalar Comal
+# Install Comal
 
-Comal es un cliente de terminal. Necesitas Node.js 22 o posterior y npm; para búsquedas de código instala también `rg` (ripgrep). No necesitas desplegar PHP, Docker ni el backend para usar la CLI. Los Artifacts privados usan la casa pública de Comal.
+Comal is a terminal client. You need Node.js 22 or later and npm; for code searches also install `rg` (ripgrep). You do not need to deploy PHP, Docker, or the backend to use the CLI. Private Artifacts use Comal's public house.
 
-## Arrancar con npx
+## Start with npx
 
-El paquete `@milpa/comal` incluye sus dependencias JavaScript; no tiene scripts de instalación y no contiene credenciales o sesiones del autor.
+The `@milpa/comal` package includes its JavaScript dependencies; it has no installation scripts and contains no author credentials or sessions.
 
 ```sh
 npx @milpa/comal
 ```
 
-El primer arranque, sin conexión configurada, muestra cómo elegir demo, Codex o tu endpoint; no intenta usar el servidor privado del autor. Usa la misma invocación en lugar de `comal` para los ejemplos de abajo. npm conserva su caché; el estado y las credenciales de Comal quedan en tu workspace y tu configuración, fuera de esa caché.
+An interactive first start opens setup inside the TUI. Press Enter to try the offline demo, choose Codex to authorize the subscription in your browser, or enter an OpenAI-compatible endpoint and let Comal discover its model. A failed connection returns to setup in the same terminal. Successful connection routing is remembered in `~/.config/comal/connection.json` (or `$XDG_CONFIG_HOME/comal/connection.json`); keys are never stored there. Explicit flags, environment settings, profiles and resumed sessions take precedence. Noninteractive invocations retain plain output.
 
-## Dejar el comando global comal
+npm keeps its cache; Comal's state and credentials remain in your workspace and your configuration, outside that cache. No repository checkout is required.
+
+## Make the global comal command
 
 ```sh
 npm install --global --ignore-scripts @milpa/comal
 
-# Si tu prefijo global requiere permisos, usa un prefijo de tu usuario:
+# If your global prefix requires permissions, use a user prefix:
 # npm install --global --prefix "$HOME/.local" --ignore-scripts @milpa/comal
 export PATH="$HOME/.local/bin:$PATH"
 comal --version
 comal --help
 ```
 
-Conserva la línea de PATH en el archivo de inicio de tu shell si utilizas ese prefijo. Si tu gestor de Node ya proporciona un prefijo de usuario, puedes omitir `--prefix "$HOME/.local"`. El paquete registra el ejecutable `comal`; no necesitas crear un alias de shell.
+Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-Puedes fijar una versión con `npx @milpa/comal@0.1.0` o `npm install --global @milpa/comal@0.1.0`. El manifiesto local de release conserva SHA-256 y la integridad SHA-512 se coteja con npm al publicar. No se afirma una firma independiente del editor.
+You can pin a version with `npx @milpa/comal@0.1.2` or `npm install --global @milpa/comal@0.1.2`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
-## Probar sin cuenta ni modelo
+## Test without account or model
 
 ```sh
 mkdir -p "$HOME/comal-practica"
 cd "$HOME/comal-practica"
-comal --demo -p 'Muestra el ciclo de herramientas'
+comal --demo -p 'Show the tool cycle'
 comal sessions
 ```
 
-La demo es un guion determinista que usa herramientas reales y crea un archivo de práctica. No es inferencia ni requiere pago. Tus sesiones se guardan en el workspace, fuera de la instalación.
+The demo is a deterministic script that uses real tools and creates a practice file. It is not inference and does not require payment. Your sessions are saved in the workspace, outside the installation.
 
-## Conectar tu modelo
+## Connect your model
 
-El endpoint heredado del entorno original es `http://llama.local:11438/`; pertenece a esa red y no se incluye un modelo con Comal. Selecciona explícitamente tu conexión:
+The legacy endpoint from the original environment is `http://llama.local:11438/`; it belongs to that network and no model is included with Comal. Explicitly select your connection:
 
 ```sh
-# Servidor compatible con OpenAI que ya tengas funcionando.
-comal --base-url http://127.0.0.1:8080/v1 --model TU_MODELO --name residente
+# OpenAI-compatible server you already have running.
+comal --base-url http://127.0.0.1:8080/v1 --model YOUR_MODEL --name resident
 
-# O tu acceso Codex compatible: autenticación y selección son pasos distintos.
+# Or your compatible Codex access: authentication and selection are separate steps.
 comal login codex
-comal --auth-provider codex --name residente
+comal --auth-provider codex --name resident
 ```
 
-Para APIs configura la clave mediante el entorno o tu gestor de secretos. No la pegues en el composer ni como argumento. Consulta https://comal.milpahq.com/academy/docs/modelos/ y https://comal.milpahq.com/academy/docs/login/ para perfiles y proveedores.
+For APIs, set the key via the environment or your secrets manager. Do not paste it in the composer or as an argument. See https://comal.milpahq.com/academy/docs/modelos/ and https://comal.milpahq.com/academy/docs/login/ for profiles and providers.
 
-## Conectar tu cuenta de Artifacts
+## Connect your Artifacts account
 
 ```sh
 comal cloud login
 comal cloud status
 ```
 
-Abre la URL que imprime Comal, entra con Google o GitHub y aprueba esa CLI. Esta cuenta autoriza Artifacts; es independiente del login y la facturación de tu modelo. Tus credenciales quedan en archivos privados de tu usuario, nunca en el paquete.
+Open the URL that Comal prints, sign in with Google or GitHub, and approve that CLI. In the current TUI you can also use `/cloud login`, or discover it with F6. `/rc` offers this login inline when needed and then opens the private remote session. Escape cancels login and returns to your composer. This account authorizes Artifacts and Remote Control; it is independent of your model login and billing. Your credentials remain in private files in your user directory, never in the package.
 
-## Actualizar o quitar
+## Update or remove
 
-Instala `@milpa/comal@VERSION` con el mismo comando y prefijo. Comprueba `comal --version`. No hay actualización silenciosa.
+Use `npx @milpa/comal@latest` for the latest release, or pin `npx @milpa/comal@VERSION`. For the optional global command, run `npm install --global @milpa/comal@latest` with the same prefix. Check `comal --version`. There is no silent update.
 
 ```sh
 npm uninstall --global @milpa/comal
 ```
 
-Esto retira el cliente; conserva las sesiones de los proyectos y las credenciales del usuario. Para desconectar Artifacts antes de quitarlo usa `comal cloud logout`; los proveedores tienen su propio `comal logout PROVEEDOR`.
+This removes the client; it keeps project sessions and user credentials. To disconnect Artifacts before removing it, use `comal cloud logout`; providers have their own `comal logout PROVIDER`.
 
-## Alcance de esta primera distribución
+## Scope of this first distribution
 
-La instalación se comprueba en Linux, desde un prefijo y un HOME vacíos. macOS y Windows mediante WSL2 son rutas pendientes de verificación en esos entornos; no se afirma soporte de Windows nativo. Chrome Lab requiere configurar tu propio host SSH/CDP. El paquete no concede acceso al laboratorio del autor.
+Installation is verified on Linux, from an empty prefix and HOME. macOS and Windows via WSL2 are paths pending verification in those environments; native Windows support is not claimed. Chrome Lab requires configuring your own SSH/CDP host. The package does not grant access to the author's lab.
 
-El paquete pertenece a la organización npm `@milpa`. `npx comal` corresponde a otro proyecto; usa el nombre completo `npx @milpa/comal`. Una licencia pública, instaladores nativos y firma del editor se resolverán por separado con el mantenedor. Documentación completa: https://comal.milpahq.com/academy/ .
+The package belongs to the npm organization `@milpa`. `npx comal` corresponds to another project; use the full name `npx @milpa/comal`. A public license, native installers, and publisher signature will be resolved separately with the maintainer. Full documentation: https://comal.milpahq.com/academy/ .
 
-El transporte de tarballs y las dependencias incluidas usan los mecanismos documentados de [npm install](https://docs.npmjs.com/cli/v12/commands/npm-install/) y [bundledDependencies](https://docs.npmjs.com/files/package.json/).
+Tarball transport and bundled dependencies use the documented mechanisms of [npm install](https://docs.npmjs.com/cli/v12/commands/npm-install/) and [bundledDependencies](https://docs.npmjs.com/files/package.json/).

package/backend/contracts/remote-commands-v1.json

@@ -0,0 +1,125 @@
+{
+  "protocol": "comal.remote.commands.v1",
+  "commands": [
+    {
+      "name": "help",
+      "arguments": "",
+      "description": "Commands available from this browser",
+      "argument_pattern": ""
+    },
+    {
+      "name": "status",
+      "arguments": "",
+      "description": "Session, provider and budget",
+      "argument_pattern": ""
+    },
+    {
+      "name": "context",
+      "arguments": "",
+      "description": "Context budget and provenance",
+      "argument_pattern": ""
+    },
+    {
+      "name": "tools",
+      "arguments": "",
+      "description": "Current tool catalog",
+      "argument_pattern": ""
+    },
+    {
+      "name": "house",
+      "arguments": "",
+      "description": "Receipts and interrupted operations",
+      "argument_pattern": ""
+    },
+    {
+      "name": "operations",
+      "arguments": "",
+      "description": "Operation contracts and effects",
+      "argument_pattern": ""
+    },
+    {
+      "name": "state",
+      "arguments": "",
+      "description": "Request and current work",
+      "argument_pattern": ""
+    },
+    {
+      "name": "audit",
+      "arguments": "",
+      "description": "Verify the local ledger",
+      "argument_pattern": ""
+    },
+    {
+      "name": "board",
+      "arguments": "",
+      "description": "Task board",
+      "argument_pattern": ""
+    },
+    {
+      "name": "work",
+      "arguments": "[resume|recover]",
+      "description": "Inspect or continue accepted work",
+      "argument_pattern": "(?:resume|recover)?"
+    },
+    {
+      "name": "compact",
+      "arguments": "",
+      "description": "Derive context without an LLM",
+      "argument_pattern": ""
+    },
+    {
+      "name": "models",
+      "arguments": "",
+      "description": "List models advertised by this provider",
+      "argument_pattern": ""
+    },
+    {
+      "name": "model",
+      "arguments": "[ID]",
+      "description": "Inspect or change the model at the next queue boundary",
+      "argument_pattern": "[^\\s\\x00-\\x1f]{1,160}"
+    },
+    {
+      "name": "effort",
+      "arguments": "[LEVEL]",
+      "description": "Inspect or change reasoning effort",
+      "argument_pattern": "(?:auto|none|minimal|low|medium|high|xhigh|max)"
+    },
+    {
+      "name": "capabilities",
+      "arguments": "[refresh]",
+      "description": "Model capability support and provenance",
+      "argument_pattern": "(?:refresh)?"
+    },
+    {
+      "name": "plugins",
+      "arguments": "[status|list]",
+      "description": "Inspect plugins",
+      "argument_pattern": "(?:status|list)?"
+    },
+    {
+      "name": "mcp",
+      "arguments": "[status|list]",
+      "description": "Inspect connected MCP servers",
+      "argument_pattern": "(?:status|list)?"
+    },
+    {
+      "name": "agents",
+      "arguments": "",
+      "description": "Inspect child runs",
+      "argument_pattern": ""
+    }
+  ],
+  "local_only": [
+    "permissions",
+    "login",
+    "logout",
+    "cloud",
+    "resume",
+    "clear",
+    "exit",
+    "quit",
+    "rc",
+    "remote-control"
+  ]
+}

package/bin/comal.mjs

@@ -1,21 +1,32 @@
 #!/usr/bin/env node
 try {
-  const args=process.argv.slice(2);
+  const originalArgs=process.argv.slice(2);
   const {readFile,access}=await import('node:fs/promises');
   const {default:path}=await import('node:path');
   const pkg=JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8'));
+  // Exact version checks remain independent of CLI modules and UI configuration.
+  if(originalArgs.length===1 && ['--version','-v'].includes(originalArgs[0])) {
+    process.stdout.write(`Comal ${pkg.version}\n`);
+  } else if(pkg.name!=='@milpa/comal') {
+    const {main}=await import('../src/cli.mjs');
+    process.exitCode=await main(originalArgs);
+  } else {
+  const {t,configureLanguage,languageArguments}=await import('../src/i18n/index.mjs');
+  const {requested,remaining:args}=languageArguments(originalArgs);
+  configureLanguage({requested});
   const configured=Object.entries(process.env).some(([key,value])=>value && /^(?:(?:COMAL|HARNESS)_(?:PROVIDER|BASE_URL|MODEL|PROVIDERS_CONFIG|PROFILE)|(?:OPENAI|ANTHROPIC|GEMINI)_(?:BASE_URL|MODEL|API_KEY))$/.test(key));
   const hasProfile=await Promise.all(['.comal/providers.json','.harness/providers.json'].map(file=>access(path.resolve(file)).then(()=>true,()=>false)));
   const firstRun=pkg.name==='@milpa/comal' && !args.length && !configured && !hasProfile.some(Boolean);
   let pipedPrompt='';
-  if(firstRun && !process.stdin.isTTY)for await(const chunk of process.stdin){pipedPrompt+=chunk;if(Buffer.byteLength(pipedPrompt)>1024*1024)throw Error('Prompt excede 1 MiB.');}
+  if(firstRun && !process.stdin.isTTY)for await(const chunk of process.stdin){pipedPrompt+=chunk;if(Buffer.byteLength(pipedPrompt)>1024*1024)throw Error(t("Prompt exceeds 1 MiB."));}
   if(args.length===1 && ['--version','-v'].includes(args[0])) {
     process.stdout.write(`Comal ${pkg.version}\n`);
-  } else if(firstRun && !pipedPrompt.trim()) {
+  } else if(firstRun && !pipedPrompt.trim() && !(process.stdin.isTTY && process.stdout.isTTY)) {
     const command=process.env.npm_command==='exec'?'npx @milpa/comal':'comal';
-    process.stdout.write(`Comal ${pkg.version} · Tu primera vuelta\n\nElige cómo empezar desde tu proyecto:\n\n  Probar sin cuenta ni modelo:\n    ${command} --demo\n\n  Conectar Codex:\n    ${command} login codex\n    ${command} --auth-provider codex\n\n  Usar tu servidor compatible con OpenAI:\n    ${command} --base-url http://127.0.0.1:8080/v1 --model TU_MODELO\n\n  Conectar tu cuenta de Artifacts (opcional):\n    ${command} cloud login\n\nGuía: https://comal.milpahq.com/academy/\n`);
+    process.stdout.write(t("Comal {v0} · Your first turn\n\nChoose how to start from your project:\n\n  Try without account or model:\n    {v1} --demo\n\n  Connect Codex:\n    {v2} login codex\n    {v3} --auth-provider codex\n\n  Use your OpenAI-compatible server:\n    {v4} --base-url http://127.0.0.1:8080/v1 --model YOUR_MODEL\n\n  Connect your Artifacts account (optional):\n    {v5} cloud login\n\nGuide: https://comal.milpahq.com/academy/\n", {v0: pkg.version, v1: command, v2: command, v3: command, v4: command, v5: command}));
   } else {
     const {main}=await import('../src/cli.mjs');
-    process.exitCode=await main(pipedPrompt.trim()?['--print','--',pipedPrompt]:args);
+    process.exitCode=await main(pipedPrompt.trim()?[...originalArgs,'--print','--',pipedPrompt]:originalArgs);
+  }
   }
 } catch(error){process.stderr.write(`Comal: ${error.message}\n`);process.exitCode=1;}

package/docs/investigation.md

@@ -1,3 +1,3 @@
-# Procedencia de Comal
+# Comal provenance
 
-Comal es una implementación independiente investigada mediante REA. El paquete incluye el cliente Node, sus herramientas y contratos compartidos. No ejecuta Claude Code para responder. Documentación: https://comal.milpahq.com/academy/
+Comal is an independent implementation researched using REA. The package includes the Node client, its tools, and shared contracts. It does not run Claude Code to produce responses. Documentation: https://comal.milpahq.com/academy/

package/governance/chrome-task-v2.json

@@ -0,0 +1,67 @@
+{
+  "profile": {
+    "name": "comal-chrome-task",
+    "version": "2",
+    "decisionIds": [
+      "COMAL-CHROME-002"
+    ]
+  },
+  "decisions": [
+    {
+      "id": "COMAL-CHROME-001",
+      "title": "La casa conserva el encargo y cierra con evidencia vigente",
+      "status": "accepted",
+      "supersedes": null,
+      "gates": [
+        {
+          "id": "task-scope",
+          "tier": "enforced",
+          "operations": [
+            "*"
+          ],
+          "boundTo": "runtime:chrome-task.scope"
+        },
+        {
+          "id": "current-evidence",
+          "tier": "enforced",
+          "operations": [
+            "WorkTaskUpdate"
+          ],
+          "boundTo": "runtime:chrome-task.close"
+        }
+      ]
+    },
+    {
+      "id": "COMAL-CHROME-002",
+      "title": "The accepted Chrome task binds exact artifact bytes through a narrow host hash capability",
+      "status": "accepted",
+      "supersedes": "COMAL-CHROME-001",
+      "gates": [
+        {
+          "id": "task-scope",
+          "tier": "enforced",
+          "operations": [
+            "*"
+          ],
+          "boundTo": "runtime:chrome-task.scope"
+        },
+        {
+          "id": "current-evidence",
+          "tier": "enforced",
+          "operations": [
+            "WorkTaskUpdate"
+          ],
+          "boundTo": "runtime:chrome-task.close"
+        },
+        {
+          "id": "artifact-hash",
+          "tier": "enforced",
+          "operations": [
+            "FileInfo"
+          ],
+          "boundTo": "runtime:chrome-task.artifact-hash"
+        }
+      ]
+    }
+  ]
+}

package/node_modules/@jitl/quickjs-ffi-types/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+quickjs-emscripten copyright (c) 2019-2024 Jake Teton-Landis
+
+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/node_modules/@jitl/quickjs-ffi-types/README.md

@@ -0,0 +1,5 @@
+# @jitl/quickjs-ffi-types
+
+This is an internal package, part of [quickjs-emscripten](https://github.com/justjake/quickjs-emscripten).
+
+See the main package for documentation.