trackops 2.0.5 → 2.0.6

package/README.md

@@ -98,11 +98,13 @@ trackops --version
 cd ruta/a/tu/proyecto
 ```
 
-4. Activa TrackOps y elige el idioma del proyecto cuando el CLI lo pida:
-
-```bash
-trackops init
-```
+4. Activa TrackOps y elige el idioma del proyecto cuando el CLI lo pida:
+
+```bash
+trackops init
+```
+
+`trackops init` funciona sobre directorios vacios, repos ya existentes y workspaces ya activados. Si lo ejecutas otra vez, refresca los artefactos gestionados. `trackops workspace migrate` queda reservado para proyectos TrackOps legacy.
 
 5. Instala OPERA:
 
@@ -141,13 +143,15 @@ Y despues reanuda:
 trackops opera bootstrap --resume
 ```
 
-8. Si OPERA completa bootstrap directo, revisa estado y continua con:
-
-```bash
-trackops opera status
-trackops next
-trackops sync
-```
+8. Si OPERA completa bootstrap directo, revisa estado y continua con:
+
+```bash
+trackops opera status
+trackops next
+trackops sync
+```
+
+Si necesitas una salida mas simple para lectores de pantalla, logs o terminales con soporte Unicode limitado, añade `--plain` o `--a11y` a cualquier comando, por ejemplo `trackops status --plain`.
 
 ### Desinstalacion global y local
 
@@ -198,16 +202,18 @@ trackops init
 trackops opera install
 ```
 
-Semantica:
-
-- `trackops init`
-  activa TrackOps en el repo
-- `trackops opera install`
-  anade OPERA cuando quieres el framework operativo completo
-- `trackops init --with-opera`
-  existe como atajo
-- `trackops init --legacy-layout`
-  existe solo por compatibilidad
+Semantica:
+
+- `trackops init`
+  activa o actualiza TrackOps en el repo, adopta repos existentes y puede reejecutarse con seguridad
+- `trackops opera install`
+  anade OPERA cuando quieres el framework operativo completo
+- `trackops init --with-opera`
+  existe como atajo
+- `trackops init --legacy-layout`
+  existe solo por compatibilidad
+
+`trackops workspace migrate` se mantiene solo para proyectos TrackOps legacy.
 
 ### Workspace split
 
@@ -262,23 +268,32 @@ trackops opera bootstrap --resume
 
 La terminal tambien debe decirte este siguiente paso al terminar el handoff.
 
-#### Ya tengo un repo
-
-Si el usuario es tecnico y el proyecto ya tiene suficiente contexto, OPERA sigue por bootstrap directo, compila `ops/contract/operating-contract.json` y recompila `ops/genesis.md`.
-
-Tambien puedes forzar el modo:
+#### Ya tengo un repo
+
+Si el usuario es tecnico y el proyecto ya tiene suficiente contexto, OPERA sigue por bootstrap directo. En ese modo crea o actualiza desde el primer paso:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+- `ops/bootstrap/open-questions.md`
+- `ops/bootstrap/quality-report.json`
+
+Despues solo compila `ops/contract/operating-contract.json` y recompila `ops/genesis.md` cuando el bootstrap ya es consistente.
+
+Tambien puedes forzar el modo:
 
 ```bash
 trackops opera install --bootstrap-mode handoff
 trackops opera install --bootstrap-mode direct
 ```
 
-Flags disponibles:
-
-- `--technical-level low|medium|high|senior`
-- `--project-state idea|draft|existing_repo|advanced`
-- `--docs-state none|notes|sos|spec_dossier|repo_docs`
-- `--decision-ownership user|shared|agent`
+Flags disponibles:
+
+- `--technical-level low|medium|high|senior`
+- `--project-state idea|draft|existing_repo|advanced`
+- `--docs-state none|notes|sos|spec_dossier|repo_docs`
+- `--decision-ownership user|shared|agent`
+
+En modo directo, `trackops opera handoff` no inventa un handoff de agente: muestra un resumen guiado de esos archivos y te dice exactamente que completar antes de reanudar.
 
 ### Entorno y secretos
 
@@ -319,12 +334,12 @@ trackops doctor locale
 
 | Comando | Descripcion |
 |---|---|
-| `trackops init [--with-opera] [--locale es\|en] [--name "..."] [--no-bootstrap] [--legacy-layout]` | Inicializa TrackOps |
+| `trackops init [--with-opera] [--locale es\|en] [--name "..."] [--no-bootstrap] [--legacy-layout]` | Inicializa o actualiza TrackOps; adopta repos existentes |
 | `trackops status` | Muestra estado operativo |
 | `trackops next` | Muestra la siguiente cola priorizada |
 | `trackops sync` | Regenera docs operativos |
 | `trackops workspace status` | Muestra layout y roots |
-| `trackops workspace migrate` | Migra un proyecto legacy |
+| `trackops workspace migrate` | Migra un proyecto TrackOps legacy |
 | `trackops env status` | Audita claves presentes y faltantes |
 | `trackops env sync` | Regenera `/.env`, `/.env.example` y el puente |
 | `trackops locale get\|set [es\|en]` | Lee o fija el idioma global |
@@ -334,9 +349,11 @@ trackops doctor locale
 | `trackops opera install [--bootstrap-mode ...] [--technical-level ...] [--project-state ...] [--docs-state ...] [--decision-ownership ...]` | Instala OPERA y decide la ruta de bootstrap |
 | `trackops opera bootstrap [--resume]` | Continua el bootstrap o ingiere el resultado del agente |
 | `trackops opera handoff [--print\|--json]` | Muestra el handoff listo para copiar al agente |
-| `trackops opera status` | Muestra estado de instalacion y bootstrap |
-| `trackops opera configure` | Reconfigura idioma o fases |
-| `trackops opera upgrade --stable [--reset]` | Reescribe artefactos gestionados a la version estable actual |
+| `trackops opera status` | Muestra estado de instalacion y bootstrap |
+| `trackops opera configure` | Reconfigura idioma o fases |
+| `trackops opera upgrade --stable [--reset]` | Reescribe artefactos gestionados a la version estable actual |
+
+Todos los comandos aceptan `--plain` y `--a11y` para una salida mas lineal y accesible.
 
 ### Skills del proyecto
 
@@ -463,11 +480,13 @@ trackops --version
 cd path/to/your/project
 ```
 
-4. Activate TrackOps and choose the project language when the CLI asks:
-
-```bash
-trackops init
-```
+4. Activate TrackOps and choose the project language when the CLI asks:
+
+```bash
+trackops init
+```
+
+`trackops init` works on empty directories, existing repositories, and already initialized workspaces. Rerunning it refreshes managed artifacts. `trackops workspace migrate` is reserved for legacy TrackOps projects.
 
 5. Install OPERA:
 
@@ -504,13 +523,15 @@ Then resume with:
 trackops opera bootstrap --resume
 ```
 
-8. If OPERA completes direct bootstrap, review status and continue with:
-
-```bash
-trackops opera status
-trackops next
-trackops sync
-```
+8. If OPERA completes direct bootstrap, review status and continue with:
+
+```bash
+trackops opera status
+trackops next
+trackops sync
+```
+
+If you need simpler output for screen readers, logs, or terminals with limited Unicode support, add `--plain` or `--a11y` to any command, for example `trackops status --plain`.
 
 ### Local activation
 
@@ -571,16 +592,25 @@ If the user is not technical, the project is still in idea stage, or documentati
 trackops opera bootstrap --resume
 ```
 
-#### I already have a repository
-
-If the user is technical and the project already has enough context, OPERA continues with direct bootstrap, compiles `ops/contract/operating-contract.json`, and recompiles `ops/genesis.md`.
-
-You can also force the mode:
+#### I already have a repository
+
+If the user is technical and the project already has enough context, OPERA continues with direct bootstrap. In that mode it creates or updates these files from the start:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+- `ops/bootstrap/open-questions.md`
+- `ops/bootstrap/quality-report.json`
+
+It only compiles `ops/contract/operating-contract.json` and recompiles `ops/genesis.md` once bootstrap becomes consistent.
+
+You can also force the mode:
 
 ```bash
-trackops opera install --bootstrap-mode handoff
-trackops opera install --bootstrap-mode direct
-```
+trackops opera install --bootstrap-mode handoff
+trackops opera install --bootstrap-mode direct
+```
+
+In direct mode, `trackops opera handoff` does not fake an agent handoff. It shows a guided summary of those files and the exact next step before resume.
 
 ### Global and local removal
 
@@ -684,9 +714,9 @@ trackops skill install <name>
 trackops skill remove <name>
 ```
 
-### Main CLI
-
-Core and OPERA commands follow the same contract as the Spanish section above, including `trackops opera handoff`, `trackops opera bootstrap --resume`, and the explicit `npm install -g trackops` runtime step.
+### Main CLI
+
+Core and OPERA commands follow the same contract as the Spanish section above, including `trackops opera handoff`, `trackops opera bootstrap --resume`, the explicit `npm install -g trackops` runtime step, and the global `--plain` / `--a11y` flags.
 
 ### Publishing
 

package/bin/trackops.js

@@ -1,13 +1,33 @@
 #!/usr/bin/env node
 
-const path = require("path");
-const config = require("../lib/config");
-const runtimeState = require("../lib/runtime-state");
-const { setLocale, t } = require("../lib/i18n");
-const pkg = require("../package.json");
+const nodeVersion = parseInt(process.versions.node, 10);
+if (nodeVersion < 18) {
+  console.error(`TrackOps requiere Node.js 18 o superior. Version actual: ${process.versions.node}`);
+  process.exit(1);
+}
 
-const command = process.argv[2];
-const args = process.argv.slice(3);
+const path = require("path");
+const config = require("../lib/config");
+const runtimeState = require("../lib/runtime-state");
+const { setLocale, t } = require("../lib/i18n");
+const fmt = require("../lib/cli-format");
+const pkg = require("../package.json");
+
+function parseCliTokens(argv) {
+  const plain = argv.includes("--plain") || argv.includes("--a11y");
+  const tokens = argv.filter((token) => !["--plain", "--a11y"].includes(token));
+  return {
+    plain,
+    command: tokens[0],
+    args: tokens.slice(1),
+  };
+}
+
+const parsed = parseCliTokens(process.argv.slice(2));
+fmt.configure({ plain: parsed.plain });
+
+const command = parsed.command;
+const args = parsed.args;
 
 function initCliLocale() {
   let projectLocale = null;
@@ -27,6 +47,7 @@ function resolveRoot() {
   const context = config.resolveWorkspaceContext();
   if (!context) {
     console.error(t("cli.error.noWorkspace"));
+    console.error(t("cli.help.initFirst"));
     process.exit(1);
   }
   return context.workspaceRoot;

package/lib/cli-format.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * CLI output formatting helpers for accessible, scannable terminal output.
+ * Supports a plain mode for screen readers, logs, and limited terminals.
+ */
+
+const state = {
+  plain: false,
+};
+
+const UNICODE_SEP = "\u2500".repeat(48);
+const PLAIN_SEP = "-".repeat(48);
+
+const STATUS_TOKENS = {
+  pending: ["\u23F3", "PENDING"],
+  in_progress: ["\uD83D\uDEA7", "IN PROGRESS"],
+  in_review: ["\uD83D\uDC40", "IN REVIEW"],
+  blocked: ["\u26D4", "BLOCKED"],
+  completed: ["\u2705", "DONE"],
+  cancelled: ["\uD83D\uDDD1\uFE0F", "CANCELLED"],
+};
+
+const CHECK_TOKENS = {
+  pass: ["\u2705", "PASS"],
+  warn: ["\u26A0\uFE0F", "WARN"],
+  fail: ["\u274C", "FAIL"],
+  pending: ["\u23F3", "PENDING"],
+};
+
+function configure(options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, "plain")) {
+    state.plain = Boolean(options.plain);
+  }
+}
+
+function isPlain() {
+  return state.plain;
+}
+
+function pick(unicodeValue, plainValue) {
+  return state.plain ? plainValue : unicodeValue;
+}
+
+function sep() {
+  console.log(pick(UNICODE_SEP, PLAIN_SEP));
+}
+
+function blank() {
+  console.log("");
+}
+
+function header(text) {
+  console.log("");
+  console.log(pick(UNICODE_SEP, PLAIN_SEP));
+  console.log(`  ${text}`);
+  console.log(pick(UNICODE_SEP, PLAIN_SEP));
+}
+
+function success(text) {
+  console.log(`  ${pick("\u2713", "OK")} ${text}`);
+}
+
+function info(text) {
+  console.log(`  ${text}`);
+}
+
+function step(label, value) {
+  if (value !== undefined) {
+    console.log(`  ${pick("\u2192", "->")} ${label}: ${value}`);
+  } else {
+    console.log(`  ${pick("\u2192", "->")} ${label}`);
+  }
+}
+
+function hint(text) {
+  console.log(`    ${text}`);
+}
+
+function warn(text) {
+  console.log(`  ${pick("\u26A0", "WARN")} ${text}`);
+}
+
+function bullet(text) {
+  console.log(`    - ${text}`);
+}
+
+function statusToken(status) {
+  const pair = STATUS_TOKENS[status] || [status, String(status || "").toUpperCase()];
+  return pick(pair[0], `[${pair[1]}]`);
+}
+
+function checkToken(status) {
+  const pair = CHECK_TOKENS[status] || [status, String(status || "").toUpperCase()];
+  return pick(pair[0], `[${pair[1]}]`);
+}
+
+function boolToken(value) {
+  return value ? pick("\u2705", "[YES]") : pick("\u274C", "[NO]");
+}
+
+module.exports = {
+  configure,
+  isPlain,
+  pick,
+  sep,
+  blank,
+  header,
+  success,
+  info,
+  step,
+  hint,
+  warn,
+  bullet,
+  statusToken,
+  checkToken,
+  boolToken,
+};

package/lib/config.js

@@ -269,14 +269,40 @@ function getOperaVersion(control) {
   return control.meta?.opera?.version || null;
 }
 
+function validateControl(control) {
+  if (!control || typeof control !== "object") throw new Error("project_control.json is not a valid object.");
+  if (!control.meta || typeof control.meta !== "object") throw new Error("project_control.json is missing required field: meta");
+  if (!Array.isArray(control.tasks)) throw new Error("project_control.json is missing required field: tasks");
+  for (let i = 0; i < control.tasks.length; i++) {
+    const task = control.tasks[i];
+    if (!task.id) throw new Error(`Task at index ${i} is missing required field: id`);
+    if (!task.status) throw new Error(`Task at index ${i} is missing required field: status`);
+  }
+}
+
 function loadControl(contextOrRoot) {
   const filePath = controlFilePath(contextOrRoot);
-  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch (err) {
+    throw new Error(`No se puede leer project_control.json.\n  Ruta: ${filePath}\n  Detalle: ${err.code === "ENOENT" ? "El archivo no existe. Ejecuta 'trackops init' primero." : err.message}`);
+  }
+  let control;
+  try {
+    control = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`project_control.json esta corrupto o no es JSON valido.\n  Ruta: ${filePath}\n  Detalle: ${err.message}`);
+  }
+  validateControl(control);
+  return control;
 }
 
-function saveControl(contextOrRoot, control) {
+function saveControl(contextOrRoot, control, options) {
   control.meta = control.meta || {};
-  control.meta.updatedAt = new Date().toISOString();
+  if (!(options && options.skipTimestamp)) {
+    control.meta.updatedAt = new Date().toISOString();
+  }
   const filePath = controlFilePath(contextOrRoot);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, JSON.stringify(control, null, 2) + "\n", "utf8");