@jahanxu/code-flow 0.1.0

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@jahanxu/code-flow",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "bin": {
+    "code-flow": "src/cli.js"
+  },
+  "files": [
+    "src/cli.js",
+    "src/core/**",
+    "src/adapters/**"
+  ]
+}

package/src/adapters/claude/settings.local.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .code-flow/scripts/cf_inject_hook.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .code-flow/scripts/cf_session_hook.py"
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/adapters/claude/skills/cf-init.md

@@ -0,0 +1,13 @@
+# cf-init
+
+初始化 code-flow 规范体系（目录、配置、spec、skill、hooks）。
+
+## Usage
+- `/cf-init`
+- `/cf-init frontend|backend|fullstack`
+
+## Command
+- `python3 .code-flow/scripts/cf_init.py [frontend|backend|fullstack]`
+
+## Notes
+- 依赖 Python 3.9+ 与 pyyaml（脚本会尝试自动安装）。

package/src/adapters/claude/skills/cf-inject.md

@@ -0,0 +1,12 @@
+# cf-inject
+
+手动注入指定领域或文件路径对应的规范（Hook 失败时回退）。
+
+## Usage
+- `/cf-inject frontend|backend`
+- `/cf-inject path/to/file.ext`
+- `/cf-inject --list-specs --domain=frontend`
+
+## Command
+- `python3 .code-flow/scripts/cf_inject.py [domain|file_path]`
+- `python3 .code-flow/scripts/cf_inject.py --list-specs --domain=frontend`

package/src/adapters/claude/skills/cf-learn.md

@@ -0,0 +1,11 @@
+# cf-learn
+
+将经验沉淀到对应规范的 Learnings 段落。
+
+## Usage
+- `/cf-learn --scope=global --content="..." `
+- `/cf-learn --scope=frontend --content="..." --file=frontend/component-specs.md`
+- `/cf-learn --scope=backend --content="..." --file=backend/logging.md`
+
+## Command
+- `python3 .code-flow/scripts/cf_learn.py --scope=global|frontend|backend --content=\"...\" [--file=spec] [--dry-run]`

package/src/adapters/claude/skills/cf-scan.md

@@ -0,0 +1,12 @@
+# cf-scan
+
+审计规范文件的 token 分布与问题提示。
+
+## Usage
+- `/cf-scan`
+- `/cf-scan --json`
+- `/cf-scan --only-issues`
+- `/cf-scan --limit=10`
+
+## Command
+- `python3 .code-flow/scripts/cf_scan.py [--json] [--only-issues] [--limit=N]`

package/src/adapters/claude/skills/cf-stats.md

@@ -0,0 +1,11 @@
+# cf-stats
+
+统计 L0/L1 规范 token 使用情况。
+
+## Usage
+- `/cf-stats`
+- `/cf-stats --human`
+- `/cf-stats --domain=frontend`
+
+## Command
+- `python3 .code-flow/scripts/cf_stats.py [--human] [--domain=frontend]`

package/src/adapters/claude/skills/cf-validate.md

@@ -0,0 +1,12 @@
+# cf-validate
+
+基于变更文件执行验证规则（类型检查/测试/lint）。
+
+## Usage
+- `/cf-validate`
+- `/cf-validate path/to/file.py`
+- `/cf-validate --files=src/a.ts,src/b.ts`
+- `/cf-validate --only-failed`
+
+## Command
+- `python3 .code-flow/scripts/cf_validate.py [file_path] [--files=...] [--only-failed] [--json-short] [--output=table]`

package/src/adapters/codex/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS
+
+Placeholder for Codex adapter.

package/src/adapters/cursor/cursorrules

@@ -0,0 +1 @@
+# Placeholder for Cursor adapter rules.

package/src/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const usage = [
+  'Usage: code-flow init',
+  '       code-flow --help'
+].join('\n');
+
+function printUsage(stream) {
+  stream.write(`${usage}\n`);
+}
+
+function fail(message) {
+  if (message) {
+    process.stderr.write(`${message}\n`);
+  }
+  printUsage(process.stderr);
+  process.exit(1);
+}
+
+function ensurePython3() {
+  const probe = spawnSync('python3', ['--version'], { stdio: 'ignore' });
+  if (probe.error || probe.status !== 0) {
+    process.stderr.write('Error: python3 is required but was not found in PATH.\n');
+    process.exit(1);
+  }
+}
+
+function copyFileIfMissing(srcFile, destFile) {
+  if (fs.existsSync(destFile)) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(destFile), { recursive: true });
+  fs.copyFileSync(srcFile, destFile);
+}
+
+function copyDirRecursive(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+      continue;
+    }
+    if (entry.isFile()) {
+      if (!fs.existsSync(destPath)) {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+
+function runInit() {
+  ensurePython3();
+
+  const cwd = process.cwd();
+  const baseDir = __dirname;
+  const coreDir = path.join(baseDir, 'core');
+  const adaptersDir = path.join(baseDir, 'adapters');
+
+  copyDirRecursive(path.join(coreDir, 'code-flow'), path.join(cwd, '.code-flow'));
+  copyFileIfMissing(path.join(coreDir, 'claude.md'), path.join(cwd, 'CLAUDE.md'));
+  copyDirRecursive(path.join(adaptersDir, 'claude'), path.join(cwd, '.claude'));
+
+  const result = spawnSync(
+    'python3',
+    ['.code-flow/scripts/cf_init.py'],
+    { stdio: 'inherit', cwd }
+  );
+
+  if (result.error) {
+    process.stderr.write(`Error: ${result.error.message}\n`);
+    process.exit(1);
+  }
+
+  process.exit(result.status ?? 0);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 1 && args[0] === '--help') {
+  printUsage(process.stdout);
+  process.exit(0);
+}
+
+if (args.length === 1 && args[0] === 'init') {
+  runInit();
+}
+
+if (args.length === 0) {
+  fail('Error: missing command.');
+}
+
+if (args.includes('--path')) {
+  fail('Error: --path is not supported; run init in the current directory.');
+}
+
+fail(`Error: unknown command "${args.join(' ')}".`);

package/src/core/code-flow/config.yml

@@ -0,0 +1,97 @@
+version: 1
+
+budget:
+    total: 2500
+    l0_max: 800
+    l1_max: 1700
+
+inject:
+    auto: true
+    code_extensions:
+        - ".py"
+        - ".ts"
+        - ".tsx"
+        - ".js"
+        - ".jsx"
+        - ".go"
+        - ".java"
+        - ".rs"
+        - ".rb"
+        - ".vue"
+        - ".svelte"
+    skip_extensions:
+        - ".md"
+        - ".txt"
+        - ".json"
+        - ".yml"
+        - ".yaml"
+        - ".toml"
+        - ".lock"
+        - ".csv"
+        - ".xml"
+        - ".svg"
+        - ".png"
+        - ".jpg"
+        - ".jpeg"
+        - ".gif"
+        - ".ico"
+        - ".pdf"
+        - ".zip"
+        - ".gz"
+        - ".tar"
+    skip_paths:
+        - "docs/**"
+        - "*.config.*"
+        - ".code-flow/**"
+        - ".claude/**"
+        - "node_modules/**"
+        - "dist/**"
+        - "build/**"
+        - "out/**"
+        - "coverage/**"
+        - ".next/**"
+        - ".cache/**"
+        - ".venv/**"
+        - "venv/**"
+        - "__pycache__/**"
+        - ".git/**"
+
+path_mapping:
+    frontend:
+        patterns:
+            - "src/components/**"
+            - "src/pages/**"
+            - "src/hooks/**"
+            - "src/styles/**"
+            - "**/*.tsx"
+            - "**/*.jsx"
+            - "**/*.css"
+            - "**/*.scss"
+        specs:
+            - "frontend/directory-structure.md"
+            - "frontend/quality-standards.md"
+            - "frontend/component-specs.md"
+        spec_priority:
+            "frontend/directory-structure.md": 1
+            "frontend/quality-standards.md": 2
+            "frontend/component-specs.md": 3
+    backend:
+        patterns:
+            - "services/**"
+            - "api/**"
+            - "models/**"
+            - "*.py"
+            - "**/*.py"
+            - "**/*.go"
+        specs:
+            - "backend/directory-structure.md"
+            - "backend/logging.md"
+            - "backend/database.md"
+            - "backend/platform-rules.md"
+            - "backend/code-quality-performance.md"
+        spec_priority:
+            "backend/directory-structure.md": 1
+            "backend/database.md": 2
+            "backend/logging.md": 3
+            "backend/code-quality-performance.md": 4
+            "backend/platform-rules.md": 5

package/src/core/code-flow/scripts/cf_core.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+import fnmatch
+import json
+import os
+
+
+def load_config(project_root: str) -> dict:
+    config_path = os.path.join(project_root, ".code-flow", "config.yml")
+    if not os.path.exists(config_path):
+        return {}
+    try:
+        import yaml
+    except Exception:
+        return {}
+    try:
+        with open(config_path, "r", encoding="utf-8") as file:
+            data = yaml.safe_load(file)
+        return data or {}
+    except Exception:
+        return {}
+
+
+def estimate_tokens(text: str) -> int:
+    return len(text) // 4
+
+
+def normalize_path(path: str) -> str:
+    return path.replace(os.sep, "/")
+
+
+def is_code_file(rel_path: str, inject_config: dict) -> bool:
+    rel_path = normalize_path(rel_path)
+    for pattern in inject_config.get("skip_paths") or []:
+        if fnmatch.fnmatch(rel_path, pattern):
+            return False
+    _, ext = os.path.splitext(rel_path)
+    if ext in (inject_config.get("skip_extensions") or []):
+        return False
+    code_exts = inject_config.get("code_extensions") or []
+    return ext in code_exts
+
+
+def match_domains(rel_path: str, mapping: dict) -> list:
+    rel_path = normalize_path(rel_path)
+    domains = []
+    for domain, cfg in (mapping or {}).items():
+        patterns = cfg.get("patterns") or []
+        for pattern in patterns:
+            if fnmatch.fnmatch(rel_path, pattern):
+                domains.append(domain)
+                break
+    return domains
+
+
+def read_specs(project_root: str, domain: str, domain_cfg: dict) -> list:
+    specs_root = os.path.join(project_root, ".code-flow", "specs")
+    specs = []
+    for rel in domain_cfg.get("specs") or []:
+        spec_path = os.path.join(specs_root, rel)
+        try:
+            with open(spec_path, "r", encoding="utf-8") as file:
+                content = file.read().strip()
+            if not content:
+                continue
+            specs.append(
+                {
+                    "path": rel,
+                    "content": content,
+                    "tokens": estimate_tokens(content),
+                    "domain": domain,
+                }
+            )
+        except Exception:
+            continue
+    return specs
+
+
+def select_specs(specs: list, budget: int, priorities: dict) -> list:
+    if budget <= 0:
+        return []
+
+    def priority(spec: dict) -> int:
+        value = priorities.get(spec.get("path"))
+        if isinstance(value, int):
+            return value
+        try:
+            return int(value)
+        except Exception:
+            return 1000
+
+    ordered = sorted(specs, key=lambda spec: (priority(spec), spec.get("path", "")))
+    selected = []
+    total = 0
+    for spec in ordered:
+        if total + spec.get("tokens", 0) <= budget:
+            selected.append(spec)
+            total += spec.get("tokens", 0)
+    return selected
+
+
+def assemble_context(specs: list, heading: str) -> str:
+    parts = [heading]
+    for spec in specs:
+        parts.append(f"### {spec['path']}")
+        parts.append(spec["content"])
+    parts.append("---")
+    parts.append("以上规范是本次开发的约束条件，生成代码必须遵循。")
+    return "\n\n".join(parts)
+
+
+def load_inject_state(project_root: str) -> dict:
+    state_path = os.path.join(project_root, ".code-flow", ".inject-state")
+    try:
+        with open(state_path, "r", encoding="utf-8") as file:
+            data = json.load(file)
+        if isinstance(data, dict):
+            return data
+    except Exception:
+        return {}
+    return {}
+
+
+def save_inject_state(project_root: str, payload: dict) -> None:
+    state_path = os.path.join(project_root, ".code-flow", ".inject-state")
+    try:
+        with open(state_path, "w", encoding="utf-8") as file:
+            json.dump(payload, file)
+    except Exception:
+        return