@chenguangyao/devflow-kit 0.1.43

package/schemas/status-surface.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devflow.dev/schemas/status-surface.schema.json",
+  "title": "devflow status JSON surface",
+  "description": "Machine-readable surface returned by devflow status --json for IDE/Web UI rendering.",
+  "type": "object",
+  "required": [
+    "type",
+    "slug",
+    "title",
+    "level",
+    "phase",
+    "source",
+    "phases",
+    "artifacts",
+    "apply",
+    "review",
+    "verify",
+    "riskSignals",
+    "workflow",
+    "pendingCheckpoint",
+    "checkpointConfirmationCard",
+    "primaryPanel",
+    "blockingReason",
+    "availableActions",
+    "nextAction"
+  ],
+  "properties": {
+    "type": { "const": "change_status_surface" },
+    "slug": { "type": "string" },
+    "title": { "type": "string" },
+    "level": { "type": ["string", "null"], "enum": ["L0", "L1", "L2", "L3", null] },
+    "phase": { "type": ["string", "null"] },
+    "source": { "type": ["object", "null"] },
+    "phases": {
+      "type": "object",
+      "required": ["current", "items", "summary"],
+      "properties": {
+        "current": { "type": ["object", "null"] },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "status", "ts", "current"],
+            "properties": {
+              "id": { "type": "string" },
+              "status": { "type": "string" },
+              "ts": { "type": ["string", "null"] },
+              "current": { "type": "boolean" }
+            },
+            "additionalProperties": true
+          }
+        },
+        "summary": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "artifacts": {
+      "type": "object",
+      "required": ["core", "optional", "directories"],
+      "properties": {
+        "core": { "type": "array", "items": { "$ref": "#/definitions/artifact" } },
+        "optional": { "type": "array", "items": { "$ref": "#/definitions/artifact" } },
+        "directories": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "apply": {
+      "type": "object",
+      "required": ["status", "currentTask", "iterations", "tasks", "summary"],
+      "properties": {
+        "status": { "type": "string" },
+        "currentTask": { "type": ["string", "null"] },
+        "iterations": { "type": "integer" },
+        "tasks": { "type": "array" },
+        "summary": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "review": {
+      "type": "object",
+      "required": ["status", "maxRounds", "rounds", "latestRound", "mustTotal", "shouldTotal", "nitTotal"],
+      "properties": {
+        "status": { "type": "string" },
+        "maxRounds": { "type": "integer" },
+        "rounds": { "type": "array" },
+        "latestRound": { "type": ["object", "null"] },
+        "mustTotal": { "type": "integer" },
+        "shouldTotal": { "type": "integer" },
+        "nitTotal": { "type": "integer" }
+      },
+      "additionalProperties": true
+    },
+    "verify": {
+      "type": "object",
+      "required": ["status", "requiredReports", "presentReports", "missingReports", "reports"],
+      "properties": {
+        "status": { "type": "string" },
+        "requiredReports": { "type": "array", "items": { "type": "string" } },
+        "presentReports": { "type": "array", "items": { "type": "string" } },
+        "missingReports": { "type": "array", "items": { "type": "string" } },
+        "reports": { "type": "array" }
+      },
+      "additionalProperties": true
+    },
+    "riskSignals": {
+      "type": "object",
+      "required": ["items", "summary"],
+      "properties": {
+        "items": { "type": "array" },
+        "summary": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "workflow": { "type": ["object", "null"] },
+    "pendingCheckpoint": { "type": ["object", "null"] },
+    "checkpointConfirmationCard": { "type": ["object", "null"] },
+    "primaryPanel": {
+      "type": "object",
+      "required": ["type", "title", "status", "actionIds"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "checkpoint",
+            "workflow_confirm",
+            "workflow_check",
+            "review_blocked",
+            "verify_start",
+            "current_step",
+            "verify_ready",
+            "apply_tasks",
+            "review_ready",
+            "phase_hint"
+          ]
+        },
+        "title": { "type": "string" },
+        "status": { "type": "string" },
+        "reasonCode": { "type": "string" },
+        "phase": { "type": ["string", "null"] },
+        "step": { "type": "string" },
+        "checkpointType": { "type": "string" },
+        "checkpointId": { "type": "string" },
+        "actionIds": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "blockingReason": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["code", "source", "severity", "message"],
+          "properties": {
+            "code": { "type": "string" },
+            "source": { "type": "string" },
+            "severity": { "type": "string", "enum": ["blocker", "warning"] },
+            "message": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+      ]
+    },
+    "availableActions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "command", "kind", "primary"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "command": { "type": ["string", "null"] },
+          "kind": { "type": "string" },
+          "primary": { "type": "boolean" },
+          "danger": { "type": "boolean" },
+          "requiresReason": { "type": "boolean" },
+          "description": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "nextAction": { "type": ["string", "null"] }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "artifact": {
+      "type": "object",
+      "required": ["name", "path", "exists"],
+      "properties": {
+        "name": { "type": "string" },
+        "path": { "type": "string" },
+        "exists": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/workflow-confirmation-surface.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devflow.dev/schemas/workflow-confirmation-surface.schema.json",
+  "title": "devflow workflow confirmation surface",
+  "description": "Machine-readable surface returned by devflow flow card --json for workflow confirmation UI.",
+  "type": "object",
+  "required": [
+    "type",
+    "slug",
+    "baseRecipe",
+    "actions",
+    "ok",
+    "status",
+    "errors",
+    "warnings",
+    "nextAction"
+  ],
+  "properties": {
+    "type": { "const": "workflow_confirmation_surface" },
+    "slug": { "type": "string" },
+    "baseRecipe": { "type": ["object", "null"] },
+    "actions": { "$ref": "#/definitions/actionMap" },
+    "ok": { "type": "boolean" },
+    "status": { "type": ["string", "null"] },
+    "errors": { "type": "array" },
+    "warnings": { "type": "array" },
+    "confirmationCard": { "$ref": "#/definitions/confirmationCard" },
+    "nextAction": { "type": ["string", "null"] }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "actionMap": {
+      "type": "object",
+      "required": ["picker", "applySelection", "check", "confirm"],
+      "properties": {
+        "picker": { "type": "string" },
+        "applySelection": { "type": "string" },
+        "check": { "type": "string" },
+        "confirm": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "confirmationCard": {
+      "type": "object",
+      "required": ["type", "title", "question", "steps", "primaryAction", "secondaryActions"],
+      "properties": {
+        "type": { "const": "workflow_confirm" },
+        "title": { "type": "string" },
+        "question": { "type": "string" },
+        "steps": { "type": "array" },
+        "primaryAction": { "$ref": "#/definitions/cardAction" },
+        "secondaryActions": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/cardAction" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "cardAction": {
+      "type": "object",
+      "required": ["id", "label", "command"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "command": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/workflow-picker.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devflow.dev/schemas/workflow-picker.schema.json",
+  "title": "devflow workflow picker surface",
+  "description": "Machine-readable surface returned by devflow flow picker --json for linear grouped skill selection UI.",
+  "type": "object",
+  "required": [
+    "type",
+    "layout",
+    "baseRecipe",
+    "status",
+    "currentStep",
+    "groups",
+    "actions"
+  ],
+  "properties": {
+    "type": { "const": "workflow_picker_surface" },
+    "layout": { "const": "linear-grouped" },
+    "baseRecipe": { "type": ["object", "null"] },
+    "status": { "type": ["string", "null"] },
+    "currentStep": { "type": ["string", "null"] },
+    "groups": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/group" }
+    },
+    "actions": { "$ref": "#/definitions/actionMap" }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "group": {
+      "type": "object",
+      "required": ["id", "label", "items"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "items": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/item" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "item": {
+      "type": "object",
+      "required": [
+        "step",
+        "skill",
+        "label",
+        "group",
+        "selected",
+        "recommended",
+        "reason",
+        "required",
+        "optional",
+        "protected",
+        "locked",
+        "source",
+        "status",
+        "installed",
+        "command"
+      ],
+      "properties": {
+        "step": { "type": "string" },
+        "skill": { "type": "string" },
+        "label": { "type": "string" },
+        "group": { "type": "string" },
+        "selected": { "type": "boolean" },
+        "recommended": { "type": "boolean" },
+        "reason": { "type": ["string", "null"] },
+        "required": { "type": "boolean" },
+        "optional": { "type": "boolean" },
+        "protected": { "type": "boolean" },
+        "locked": { "type": "boolean" },
+        "source": { "type": ["string", "null"] },
+        "status": { "type": ["string", "null"] },
+        "installed": { "type": "boolean" },
+        "command": { "type": ["string", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "actionMap": {
+      "type": "object",
+      "required": ["card", "check", "applySelection", "confirm", "suggest"],
+      "properties": {
+        "card": { "type": "string" },
+        "check": { "type": "string" },
+        "applySelection": { "type": "string" },
+        "confirm": { "type": "string" },
+        "suggest": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+'use strict';
+
+/**
+ * Auto-install devflow skills to user-wide IDE dirs after `npm i -g`.
+ *
+ * Behavior contract (intentionally conservative):
+ *  - Only runs for global installs (`npm_config_global === 'true'`). Local
+ *    `npm install` (whether in our own repo for devDeps, or as a transitive
+ *    dependency of some other package) is filtered here and never reaches
+ *    the install logic. This is the ONLY guard we need against "dev-on-self":
+ *    when a developer runs `npm install` inside this repo, it isn't global,
+ *    so we already skip. Conversely, `npm i -g .` or `npm i -g <pkg>` from
+ *    inside this repo IS a deliberate global install — we should honour it.
+ *  - Skips when CI=1 or DEVFLOW_SKIP_POSTINSTALL=1.
+ *  - Installs one central skill copy under ~/.devflow/skills/devflow-kit, then
+ *    links ~/.cursor, ~/.claude and ~/.agents to it.
+ *  - Never fails the parent npm install — any error is logged as a warning.
+ *
+ * Manual recovery: `devflow skills install --scope=user`.
+ */
+
+function bail(msg) {
+  if (msg) console.log(`[devflow] ${msg}`);
+  process.exit(0);
+}
+
+function warn(msg) {
+  console.warn(`[devflow] ${msg}`);
+}
+
+// 1. Opt-outs
+if (process.env.DEVFLOW_SKIP_POSTINSTALL) bail('DEVFLOW_SKIP_POSTINSTALL set, skip skill auto-install');
+if (process.env.CI === 'true' || process.env.CI === '1') bail('CI environment, skip skill auto-install');
+
+// 2. Only for global installs
+//    npm sets npm_config_global=true under `-g`. pnpm/yarn classic also set this for `-g`.
+//    This single check handles all "dev-on-self" cases:
+//      - `cd devflow-kit && npm install`            → unset, skip
+//      - `cd devflow-kit && npm i -g .`             → true, install (intentional)
+//      - `cd devflow-kit && npm i -g @chen.../...`  → true, install (intentional)
+if (process.env.npm_config_global !== 'true') bail();
+
+// 3. Lazy-require — keeps cold-path failures harmless
+let skills;
+try {
+  skills = require('../src/cli/commands/skills.js');
+} catch (err) {
+  warn(`could not load skill installer (${err.message}); run "devflow skills install --scope=user" manually`);
+  process.exit(0);
+}
+
+// 4. Bootstrap helper for ~/.devflow/providers.json (loaded lazily; never
+//    fatal if it can't be required — older installs may not ship this file yet).
+let userconfig;
+try {
+  userconfig = require('../src/providers/userconfig.js');
+} catch (err) {
+  warn(`could not load user-config helper (${err.message})`);
+}
+
+(async () => {
+  // 5. Always bootstrap ~/.devflow/providers.json — even if skills are
+  //    already present, the config file is independent and may not exist yet
+  //    (e.g., upgrading from <0.1.5).
+  if (userconfig) {
+    try {
+      const uc = await userconfig.ensureUserConfig();
+      if (uc.created.providers) {
+        console.log(`[devflow] created empty provider config: ${uc.file} (chmod 0600)`);
+        console.log('[devflow]   add providers via:  devflow provider add <name>');
+      }
+      if (uc.created.example) {
+        console.log(`[devflow] created provider example: ${uc.example}`);
+        console.log('[devflow]   copy needed entries into providers.json; keep personal secrets in env vars.');
+      }
+    } catch (err) {
+      warn(`user config bootstrap failed: ${err.message}`);
+    }
+  }
+
+  // 6. Always reinstall/update skills on every global install.
+  //    The user-wide path stores one central copy and links each IDE namespace
+  //    to it, so repeated global installs act as an in-place upgrade.
+  let alreadyInstalled = false;
+  try { alreadyInstalled = skills.userSkillsInstalled(); } catch (_) { /* ignore */ }
+
+  const verb = alreadyInstalled ? 'updating' : 'installing';
+  console.log(`[devflow] ${verb} skills to ~/.devflow/skills/devflow-kit and linking IDE skill dirs …`);
+  try {
+    const dests = skills.USER_SCOPE_TARGETS.map((k) => ({ key: k, dest: skills.TARGET_MAP[k] }));
+    const out = await skills.installToDests(process.cwd(), dests, { quiet: true, linkMode: 'central' });
+    for (const s of out) console.log(`[devflow] ${s.count} skills → ${s.path}`);
+    console.log(`[devflow] skills ${verb} done.`);
+    if (!alreadyInstalled) console.log('[devflow] next: cd <your-repo> && devflow init');
+  } catch (err) {
+    warn(`skill auto-${verb} failed: ${err.message}`);
+    warn('install will continue; run "devflow skills install --scope=user" later');
+  }
+})();