@polymorphism-tech/morph-spec 8.11.0 → 8.14.0

package/src/commands/project/claim.js

@@ -4,19 +4,32 @@
  *
  * Claims are acquired and heartbeaten AUTOMATICALLY (SessionStart hook +
  * telemetry hook), so the operator never has to remember anything. This command
- * exists for the case automation cannot cover: a session that died without
- * releasing, leaving a claim that keeps warning everyone until its TTL expires.
+ * exists for the two cases automation cannot cover:
+ *   - a session that died without releasing, leaving a claim that keeps
+ *     warning everyone until its TTL expires (`--release`);
+ *   - an operator switching this SAME session/tree to a different feature
+ *     mid-task. `morph-spec claim <feature>` (no flags) ACQUIRES it, moving
+ *     the tree's previous claim in the same step — a manual release-then-
+ *     reclaim was observed to just not happen mid-task, and the silent no-op
+ *     this used to be (any unclaimed feature name printed "nothing here" and
+ *     changed nothing) was worse: it looked like a query, not a skipped write.
  *
- * Read-only by default (`--list`); the only mutation is `--release`.
- * Always exits 0 except on a genuine misuse — the claim system is advisory and
- * must never become a source of hard failures.
+ * `--list` forces the read-only view even when a feature is named. `--release`
+ * is the only other mutation. Always exits 0 except on a genuine misuse — the
+ * claim system is advisory and must never become a source of hard failures.
  */
 
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { resolve } from 'path';
 import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
-import { listClaims, releaseClaim, claimAge } from '../../../framework/hooks/shared/claim-registry.js';
+import {
+  acquireClaim,
+  foreignClaim,
+  listClaims,
+  releaseClaim,
+  claimAge,
+} from '../../../framework/hooks/shared/claim-registry.js';
 
 /** Resolve the repo's shared git common dir — where claims live. */
 function gitCommonDirOf(cwd) {
@@ -25,6 +38,52 @@ function gitCommonDirOf(cwd) {
   return common ? resolve(root, common) : null;
 }
 
+const norm = (p) => String(p ?? '').replace(/\\/g, '/');
+
+/**
+ * Acquire `feature`'s claim, moving it in the same step if this tree already
+ * holds a live claim on a different feature.
+ *
+ * "This tree's own claim" is identified by PATH, not session id: the CLI has
+ * no access to the Claude Code session id SessionStart stamps (that only
+ * reaches hooks, via stdin JSON) — path is the one honest signal a manual
+ * invocation shares with the automatic claim it may be replacing. Re-using
+ * that claim's session id when re-acquiring keeps the move from reading as a
+ * takeover of a stranger.
+ */
+function acquireOrMove(feature, { cwd, gitCommonDir, json }) {
+  const here = norm(cwd);
+  const previousHere = listClaims(gitCommonDir)
+    .find((c) => c.live && c.feature !== feature && norm(c.path) === here);
+  const takenFrom = foreignClaim(feature, { gitCommonDir, sessionId: previousHere?.sessionId });
+
+  if (previousHere) releaseClaim(previousHere.feature, { gitCommonDir });
+  const identity = previousHere?.sessionId || `cli-${process.pid}`;
+  acquireClaim(feature, { gitCommonDir, sessionId: identity, pid: process.pid, path: cwd });
+
+  if (json) {
+    console.log(JSON.stringify({
+      feature,
+      claimed: true,
+      movedFrom: previousHere?.feature ?? null,
+      tookOverFrom: takenFrom ? { pid: takenFrom.pid, path: takenFrom.path } : null,
+    }));
+    process.exit(0);
+  }
+
+  console.log(previousHere
+    ? chalk.green(`\n✅ Claim movido de "${previousHere.feature}" para "${feature}".\n`)
+    : chalk.green(`\n✅ Claim de "${feature}" adquirido.\n`));
+  if (takenFrom) {
+    console.log(chalk.yellow(
+      `⚠️  "${feature}" tinha claim VIVO de outra sessão (pid ${takenFrom.pid}` +
+      `${takenFrom.path ? ` · ${takenFrom.path}` : ''}, visto há ${claimAge(takenFrom)}) — assumido agora. ` +
+      'Confirme com a outra sessão antes de finish/archive/delete.\n'
+    ));
+  }
+  process.exit(0);
+}
+
 /**
  * @param {string|undefined} feature
  * @param {{ release?: boolean, list?: boolean, json?: boolean, cwd?: string }} [options]
@@ -61,7 +120,17 @@ export function claimCommand(feature, options = {}) {
     process.exit(0);
   }
 
-  // Default and --list are the same read: the whole board, or one feature.
+  // `morph-spec claim <feature>` (no --release, no --list) is the manual
+  // acquire/move half of B1 — automation (SessionStart + heartbeat) covers the
+  // common case; this covers switching this session to a different feature
+  // mid-task without a release-then-reclaim dance. `--list` forces the
+  // read-only view below even when a feature is named.
+  if (feature && !options.list) {
+    acquireOrMove(feature, { cwd, gitCommonDir, json: options.json });
+    return;
+  }
+
+  // No feature (or explicit --list): the read-only board, whole or filtered.
   const all = listClaims(gitCommonDir);
   const rows = feature ? all.filter((c) => c.feature === feature) : all;
 

package/src/commands/state/advance.js

@@ -67,6 +67,34 @@ function missingPhaseArtifacts(phase, featurePath) {
   }
 }
 
+/**
+ * When a required artifact is absent HERE, check whether it exists in the
+ * worktree that owns this feature. `feature.json` travels committed on
+ * `morph/{feature}`, so a feature developed in a worktree has its artifacts
+ * there and only a scaffold in the primary root — running `advance` from the
+ * root then demanded a file that already exists, one directory over.
+ *
+ * Message-only: this never reads state for a decision and never writes across
+ * trees. It replaces a misleading error with an accurate one.
+ *
+ * Fail-open — no git, no worktree, or any error yields null (today's message).
+ *
+ * @returns {Promise<{path: string, branch: string|null, present: string[]}|null>}
+ */
+async function artifactsLiveInWorktree(featureName, missing) {
+  try {
+    const { findWorktreeForFeature } = await import('../project/worktree.js');
+    const wt = findWorktreeForFeature(featureName, process.cwd());
+    if (!wt?.path) return null;
+
+    const base = join(wt.path, '.morph', 'features', featureName);
+    const present = missing.filter((rel) => existsSync(join(base, rel)));
+    return present.length ? { path: wt.path, branch: wt.branch, present } : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Resolve who approved, honestly (mirrors approve.js — no fake human signatures). */
 function resolveApprovedBy(options) {
   if (options.approver) return options.approver;
@@ -104,6 +132,21 @@ export async function advanceCommand(featureName, options = {}) {
     // the defect again.
     const missingArtifacts = missingPhaseArtifacts(phase, featurePath);
     if (missingArtifacts.length && !options.force) {
+      // Divergence, not absence: name the tree that actually holds the work
+      // instead of asking for a file that exists in it.
+      const elsewhere = await artifactsLiveInWorktree(featureName, missingArtifacts);
+      if (elsewhere) {
+        console.error(chalk.red(`\n❌ A fase "${phase}" de "${featureName}" não pode ser encerrada A PARTIR DESTA ÁRVORE.`));
+        console.error(chalk.gray('   Os artefatos não estão ausentes — eles vivem no worktree dono desta feature:'));
+        for (const rel of elsewhere.present) console.error(chalk.gray(`   • ${rel}`));
+        console.error(chalk.gray(`\n   Worktree: ${elsewhere.path}${elsewhere.branch ? ` (branch ${elsewhere.branch})` : ''}`));
+        console.error(chalk.gray('   Rode o comando LÁ — o gate é gravado no feature.json daquela árvore:'));
+        console.error(chalk.cyan(`     cd "${elsewhere.path}" && morph-spec advance ${featureName}`));
+        console.error(chalk.yellow('\n   NÃO use --force aqui: ele carimbaria o gate na cópia da raiz, duplicando'));
+        console.error(chalk.yellow('   uma aprovação que a outra árvore já tem e invertendo a ordem dos gates.\n'));
+        process.exit(1);
+      }
+
       console.error(chalk.red(`\n❌ A fase "${phase}" não pode ser encerrada — artefato(s) obrigatório(s) ausente(s):`));
       for (const rel of missingArtifacts) console.error(chalk.gray(`   • ${rel}`));
       console.error(chalk.gray('\n   Produza o artefato e rode de novo, ou passe --force para avançar assim mesmo.\n'));

package/src/lib/validators/nextjs/next-component-validator.js

@@ -28,8 +28,34 @@ const EVENT_HANDLER_PATTERNS = [
   /\bonFocus\b/,
   /\bonBlur\b/,
   /\bonKeyDown\b/,
+  // Qualquer outro handler de evento em JSX (onMouseEnter, onKeyUp, onScroll, onDrop…).
+  // Sem isto, a lista fechada acima transforma interatividade legítima em falso-positivo.
+  /\bon[A-Z]\w*\s*=\s*\{/,
 ];
 
+/**
+ * Chamada de QUALQUER hook, não só os sete nativos: `useRouter()`, `useQuery()`, `useForm<T>()`.
+ * O `[<(]` é o que faz `useState<Record<string, string>>(` contar — um hook com argumento de
+ * tipo não casa com `useState\s*\(` e passava despercebido.
+ */
+const HOOK_CALL_PATTERN = /\buse[A-Z]\w*\s*[<(]/;
+
+/**
+ * APIs de React que só existem no cliente. `forwardRef` e `createContext` lançam em Server
+ * Component, então um módulo que os usa PRECISA da diretiva, mesmo sem hook nem handler.
+ */
+const CLIENT_ONLY_APIS = [/\bforwardRef\b/, /\bcreateContext\b/];
+
+/** Globais de browser: quem os toca não roda no servidor. */
+const BROWSER_GLOBALS = /\b(window|document|localStorage|sessionStorage|navigator)\s*[.[]/;
+
+/**
+ * Pacotes cujos componentes são client-only. O caso que mais gerava ruído é o wrapper de
+ * shadcn/Radix: ele só reexporta primitivas, então não tem hook nem handler no próprio
+ * arquivo — e era acusado para sempre, apesar de estar correto.
+ */
+const CLIENT_ONLY_IMPORTS = /from\s+['"](@radix-ui\/|sonner|@react-pdf\/|file-saver|framer-motion|motion\/|recharts|next\/navigation|react-hook-form|@tanstack\/react-query|embla-carousel|cmdk|vaul|react-day-picker|input-otp|@dnd-kit\/)/;
+
 /** Next.js special files exempt from naming checks */
 const NEXTJS_SPECIAL_FILES = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx', 'route.ts', 'middleware.ts'];
 
@@ -75,7 +101,17 @@ export function validateNextComponent(content, filePath) {
   if (hasUseClient) {
     const hasEventHandlers = EVENT_HANDLER_PATTERNS.some(pattern => pattern.test(content));
     const hasClientHooks = CLIENT_HOOKS.some(hook => new RegExp(`\\b${hook}\\b`).test(content));
-    if (!hasEventHandlers && !hasClientHooks) {
+    // Só acusa quando NENHUM sinal de necessidade de cliente aparece. Um falso-positivo aqui
+    // pede a remoção de uma diretiva que o build precisa, então a checagem erra para o lado
+    // de ficar calada.
+    const needsClient =
+      hasEventHandlers ||
+      hasClientHooks ||
+      HOOK_CALL_PATTERN.test(content) ||
+      CLIENT_ONLY_APIS.some(pattern => pattern.test(content)) ||
+      BROWSER_GLOBALS.test(content) ||
+      CLIENT_ONLY_IMPORTS.test(content);
+    if (!needsClient) {
       issues.push({
         type: 'warning',
         message: "'use client' directive present but no interactivity detected (no hooks, no event handlers)",

package/src/utils/hooks-installer.js

@@ -14,8 +14,16 @@ import { existsSync, chmodSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
 
-/** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '3.4.0';
+/**
+ * Current hooks schema version — bump when hook definitions change.
+ *
+ * 3.5.0 keeps the same registry entries but changes what the installed hooks
+ * DO: state is now resolved from the target path's working tree instead of the
+ * session's. The hook files are re-copied unconditionally (`copyDirectory`
+ * defaults to `overwrite: true`), so the bump does not gate delivery — it makes
+ * `morph-spec update` report the change honestly instead of "already current".
+ */
+const HOOKS_VERSION = '3.5.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';