@flydocs/cli 0.5.0-beta.0

package/template/.flydocs/templates/scripts/check-design-system.template.mjs

@@ -0,0 +1,179 @@
+/**
+ * Design System Validation Script
+ * 
+ * Scans source files for design system violations.
+ * Configurable forbidden/allowed patterns.
+ * 
+ * Usage: node scripts/check-design-system.mjs
+ * 
+ * Configure by editing the FORBIDDEN_PATTERNS and ALLOWED_PATTERNS arrays.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ROOT = process.cwd()
+const SRC_DIR = path.join(ROOT, 'src')
+
+const FILE_EXTENSIONS = new Set(['.ts', '.tsx', '.css', '.jsx', '.js'])
+
+/**
+ * Forbidden patterns - these will cause validation to fail
+ * 
+ * Customize based on your design system:
+ * - Add patterns for hardcoded values you want to catch
+ * - Remove patterns that don't apply to your framework
+ */
+const FORBIDDEN_PATTERNS = [
+  {
+    name: 'Hardcoded spacing arbitrary values (p-/m-/gap-[..px])',
+    regex: /\b(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-\[[0-9.]+px\]/g,
+  },
+  {
+    name: 'Hardcoded radius arbitrary values (rounded-[..px])',
+    regex: /\brounded-\[[0-9.]+px\]/g,
+  },
+  {
+    name: 'Hardcoded hex colors (#fff/#ffffff)',
+    regex: /#[0-9a-fA-F]{3,8}/g,
+  },
+  {
+    name: 'Hardcoded rgba() colors',
+    regex: /rgba\(/g,
+  },
+]
+
+/**
+ * Allowed patterns - these are exceptions that won't be flagged
+ * 
+ * Common exceptions:
+ * - Layout/intrinsic sizing (w-[Xpx], h-[Xpx], max-w-[Xpx])
+ * - Specific one-off values that are documented
+ */
+const ALLOWED_PATTERNS = [
+  // Layout/intrinsic sizing whitelist
+  /\b(max-w|min-w|w|h|max-h|min-h)-\[[0-9.]+px\]/g,
+  // Thin borders
+  /\bborder-\[0\.5px\]/g,
+]
+
+/**
+ * Paths to skip during validation
+ * 
+ * Add paths that should not be checked:
+ * - Style definition files
+ * - Mocks and test utilities
+ * - Generated files
+ */
+const SKIP_PATH_FRAGMENTS = [
+  `${path.sep}src${path.sep}styles${path.sep}`,
+  `${path.sep}src${path.sep}mocks${path.sep}`,
+  `${path.sep}src${path.sep}test${path.sep}`,
+  `${path.sep}CLAUDE.md`,
+  `${path.sep}node_modules${path.sep}`,
+]
+
+function shouldSkipFile(filePath) {
+  return SKIP_PATH_FRAGMENTS.some((frag) => filePath.includes(frag))
+}
+
+function listFilesRecursive(dirPath) {
+  const results = []
+
+  if (!fs.existsSync(dirPath)) {
+    return results
+  }
+
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true })
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name)
+    if (entry.isDirectory()) {
+      results.push(...listFilesRecursive(fullPath))
+      continue
+    }
+
+    const ext = path.extname(entry.name)
+    if (FILE_EXTENSIONS.has(ext)) {
+      results.push(fullPath)
+    }
+  }
+
+  return results
+}
+
+function maskAllowed(text) {
+  let masked = text
+  for (const allowed of ALLOWED_PATTERNS) {
+    masked = masked.replaceAll(allowed, '')
+  }
+  return masked
+}
+
+function findMatches(content, regex) {
+  const matches = []
+
+  const re = new RegExp(regex.source, regex.flags)
+  let m
+  while ((m = re.exec(content)) !== null) {
+    matches.push({ index: m.index, match: m[0] })
+  }
+
+  return matches
+}
+
+function getLineInfo(content, index) {
+  const upToIndex = content.slice(0, index)
+  const line = upToIndex.split('\n').length
+  const lineStart = upToIndex.lastIndexOf('\n') + 1
+  const lineEnd = content.indexOf('\n', index)
+  const end = lineEnd === -1 ? content.length : lineEnd
+  const lineText = content.slice(lineStart, end)
+  return { line, lineText }
+}
+
+function main() {
+  if (!fs.existsSync(SRC_DIR)) {
+    console.error('Cannot find src/ directory to scan.')
+    process.exit(2)
+  }
+
+  const files = listFilesRecursive(SRC_DIR).filter((f) => !shouldSkipFile(f))
+
+  const violations = []
+
+  for (const filePath of files) {
+    const raw = fs.readFileSync(filePath, 'utf8')
+    const content = maskAllowed(raw)
+
+    for (const rule of FORBIDDEN_PATTERNS) {
+      const matches = findMatches(content, rule.regex)
+      for (const match of matches) {
+        const { line, lineText } = getLineInfo(raw, match.index)
+        violations.push({
+          file: path.relative(ROOT, filePath),
+          line,
+          rule: rule.name,
+          snippet: lineText.trim(),
+        })
+      }
+    }
+  }
+
+  if (violations.length === 0) {
+    console.log('✅ Design system check passed.')
+    return
+  }
+
+  console.error(`❌ Design system check failed: ${violations.length} violation(s) found.\n`)
+  for (const v of violations) {
+    console.error(`  ${v.file}:${v.line}`)
+    console.error(`    Rule: ${v.rule}`)
+    console.error(`    Code: ${v.snippet}\n`)
+  }
+
+  process.exit(1)
+}
+
+main()
+
+

package/template/.flydocs/version

@@ -0,0 +1 @@
+0.4.0

package/template/AGENTS.md

@@ -0,0 +1,95 @@
+# FlyDocs Agent Instructions
+
+Prefer reading project documentation over guessing from training data.
+When performing workflow, issue management, or process tasks, consult the
+relevant documentation files before acting.
+
+## Rules
+
+1. **Use scripts for all issue operations.** Create, transition, comment, assign — execute scripts, don't describe actions.
+2. **Every status transition gets a comment.** No silent moves.
+3. **Assignment required before In Progress.** Always assign before starting work.
+4. **Checkboxes live in issue description, never comments.** Update the description to track progress.
+5. **Session wrap posts a summary.** Summarize progress at end of session.
+6. **No secrets in commits.** Never commit `.env`, credentials, or API keys.
+
+## Workflow
+
+The development lifecycle follows seven stages:
+
+```
+Capture → Refine → Activate → Implement → Review → Validate → Close
+```
+
+| Stage | What Happens |
+|-------|--------------|
+| Capture | Create issue from input (feature, bug, chore, idea) |
+| Refine | Triage, fill template, set priority and estimate |
+| Activate | Assign to person, transition to In Progress |
+| Implement | Build incrementally, document decisions, self-review |
+| Review | Code quality check against acceptance criteria |
+| Validate | User acceptance testing, collect approval |
+| Close | Verify approval, mark as Done |
+
+Detailed procedures: `.claude/skills/flydocs-workflow/`
+
+## Issue Operations
+
+Scripts handle all issue management. The active backend (local files or cloud provider) determines the implementation.
+
+**Available operations:** create issue, transition status, add comment, list issues, get issue details, assign, update description, status summary.
+
+Script location: `.claude/skills/flydocs-local/scripts/` or `.claude/skills/flydocs-cloud/scripts/`
+
+## Premium Skills
+
+| Skill | Documentation |
+|-------|---------------|
+| Figma Integration | `.claude/skills/flydocs-figma/` — design extraction, token mapping |
+| Cost Estimation | `.claude/skills/flydocs-estimates/` — AI token/labor estimates (opt-in) |
+
+## Writing Style
+
+When writing or editing any copy — product docs, marketing pages, website copy, wikis, etc:
+
+- Write like a sharp colleague, not a brochure. Clear, confident, human.
+- Active voice by default. "We built X" not "X was built to enable..."
+- Vary sentence rhythm. Short sentences land. Longer ones can unpack an idea when needed.
+- Kill corporate filler: "leverage", "utilize", "facilitate", "in order to", "it should be noted that", "best-in-class", "robust."
+- Use "you" and "we" naturally. Talk to the reader, not past them.
+- Technical accuracy matters — but explain concepts plainly before going deep.
+- No emoji. No exclamation marks. No hype. Let the product speak through clarity, not enthusiasm.
+- Prefer concrete over abstract. "Cuts deploy time from 20 minutes to 3" beats "dramatically accelerates deployment workflows."
+- One idea per paragraph. If a sentence doesn't earn its place, cut it.
+- Don't repeat the same stat or claim more than once per page. Cross-page repetition is fine — readers land on individual pages.
+- When differentiating, name what the alternative does and where it falls short. Don't just assert we're better — show the specific gap.
+
+## Project Context
+
+| File | Purpose |
+|------|---------|
+| `flydocs/context/project.md` | Product scope, tech stack, active priorities |
+| `.flydocs/config.json` | Configuration — tier, provider, labels, active projects |
+
+<!-- flydocs:skills-manifest:start -->
+## Skills Index
+
+IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
+Consult the relevant skill BEFORE writing code or making workflow decisions.
+
+| Skill | Triggers | Entry |
+|-------|----------|-------|
+| flydocs-cloud | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md |
+| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort | .claude/skills/flydocs-estimates/SKILL.md |
+| flydocs-figma | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system | .claude/skills/flydocs-figma/SKILL.md |
+| flydocs-local | create issue, transition, comment, list issues, assign, update description, status summary, local | .claude/skills/flydocs-local/SKILL.md |
+| flydocs-workflow | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue | .claude/skills/flydocs-workflow/SKILL.md |
+<!-- flydocs:skills-manifest:end -->
+
+## Platform Configuration
+
+| Platform | Primary Config |
+|----------|----------------|
+| Claude Code | `.claude/CLAUDE.md` |
+| Cursor | `.cursor/rules/*.mdc` |
+| Codex / Windsurf / Others | This file (`AGENTS.md`) |

package/template/CHANGELOG.md

@@ -0,0 +1,271 @@
+# Changelog
+
+All notable changes to FlyDocs Core are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.4.0] — 2026-02-18
+
+### Added
+- **Context Graph skill** (`flydocs-context-graph`) — relationship-aware knowledge
+  graph that connects skills, ADRs, issues, modules, and sessions. Implemented as
+  ADR-006 across five phases:
+  - `graph_build.py` — scans skills and ADRs, extracts cross-references, produces
+    `flydocs/context/graph.json`. Manual nodes/edges preserved on rebuild.
+  - `graph_query.py` — BFS traversal with depth, relationship type, and direction
+    filters. Outputs compressed markdown or JSON.
+  - `graph_update.py` — incremental add/remove for nodes and edges.
+  - `graph_context.py` — assembles compressed context block (~200-400 tokens) for
+    the prime hook given active issue and git branch.
+  - `graph_session.py` — records session outcomes as graph nodes with WORKED_ON
+    and PRODUCED edges for cross-session continuity.
+- **Automatic context injection** — `prompt-submit.py` hook now calls `graph_context.py`
+  every prompt. Agents receive a temporal anchor (current date) and related decisions,
+  skills, and prior session summaries without any manual effort.
+- **Skill ordering in manifest** — `generate_manifest.py` reads PRECEDES edges from
+  the graph and adds a "Loads After" column to the skills index table.
+- **Install-time graph generation** — both fresh install and update paths call
+  `graph_build.py` after skill installation. Every FlyDocs project gets a context
+  graph automatically.
+
+### Changed
+- **Session wrap procedure** — `session.md` now includes a step to record session
+  outcomes in the context graph via `graph_session.py`. Skips silently if not installed.
+- **Session staleness policy** — session nodes within 7 days get full weight, linear
+  decay to 30 days, then excluded from context.
+
+### Migration
+- **`.gitignore` update** — `flydocs/context/graph.json` is automatically added to
+  `.gitignore` during update if missing. The graph is gitignored because it contains
+  session-specific data and can be rebuilt from sources.
+
+---
+
+## [0.3.10] — 2026-02-17
+
+### Fixed
+- **API null data crash** (FLY-178) — `flydocs_api.py` now normalizes `null` data
+  responses to empty dict before returning. Fixes `AttributeError` crashes in all
+  20+ scripts when Linear returns API errors. `create_issue.py` also retries without
+  labels when label IDs are rejected (stale config after team migration).
+- **`assign_milestone.py` flag parsing** (FLY-179) — rewritten with argparse.
+  Now supports both positional (`assign_milestone.py REF UUID`) and flag
+  (`--milestone UUID`) syntax. Previously `--milestone` was captured as the
+  milestone ID value.
+- **`list_milestones.py` missing fields** (FLY-180) — GraphQL query now includes
+  `sortOrder` and `project { id name }`. Output sorted by project then sortOrder.
+- **Community skills recommendation UI** (FLY-48) — rendering artifacts resolved
+  by the `prompt_community_skills()` rewrite in 0.3.9.
+
+---
+
+## [0.3.9] — 2026-02-17
+
+### Added
+- **Skill search and install CLI** (ENG-443) — `flydocs skills` subcommand with
+  `search`, `add`, `remove`, and `list` operations. Search the curated community
+  skills catalog, install from known names or GitHub repo references, and manage
+  installed skills post-install. Platform skills (`flydocs-*`) are guarded from
+  modification. Installs validate SKILL.md frontmatter, copy cursor rules, update
+  config, and regenerate the skill manifest automatically.
+- **Install.sh skill discovery update** (ENG-445) — community skill installation
+  now delegates to `skill_manager.py` (full directory download with validation)
+  instead of single-file curl. Added `--yes`/`-y` flag for non-interactive mode.
+  Enhanced stack detection: tsconfig.json (TypeScript), vitest, jest, testing-library.
+
+---
+
+## [0.3.8] — 2026-02-14
+
+### Added
+- **`create_issue.py --description-file` and stdin** — both cloud and local tiers now
+  accept `--description-file PATH` or piped stdin for issue descriptions. Eliminates
+  the two-step create + update_description workaround for long descriptions.
+- **`update_issue.py --title`** — cloud tier bulk update script now supports renaming
+  issues via `--title "new title"`.
+
+---
+
+## [0.3.7] — 2026-02-11
+
+### Added
+- **Skill manifest generator** (ENG-442) — `generate_manifest.py` scans SKILL.md
+  frontmatter and produces a compressed skills index table. Injected into CLAUDE.md
+  and AGENTS.md between `<!-- flydocs:skills-manifest -->` markers. Bridges skill
+  discovery with on-demand retrieval — agents see triggers in always-loaded context.
+- **`.flydocs/scripts/` owned directory** — shared utility scripts (not mechanism
+  scripts) now have a dedicated home, managed by manifest.json ownership.
+
+---
+
+## [0.3.6] — 2026-02-10
+
+### Added
+- **Milestone, project, and dueDate in issue output** — `list_issues.py` now returns
+  `milestone`, `milestoneId`, `milestoneSortOrder`, `project`, `projectId`, and `dueDate`
+  for every issue. `get_issue.py` returns the same fields (minus `milestoneSortOrder`).
+  Enables milestone-grouped dashboards and priority-based session planning.
+
+### Changed
+- **Session start workflow rewritten** — `session.md` now instructs agents to group issues
+  by milestone (in milestone order), identify the current milestone, suggest a starting point
+  based on priority cascade (blocked → in-progress → due soon → highest priority in current
+  milestone), and surface other product issues separately. Never shows issues outside
+  the product scope.
+
+### Fixed
+- **`create_milestone.py` missing projectId** — `ProjectMilestoneCreateInput` requires a
+  `projectId`. Script now defaults to first `activeProject` from config, with `--project`
+  flag to override.
+
+---
+
+## [0.3.5] — 2026-02-10
+
+### Added
+- **`list_projects.py` product scope** (ENG-475) — now respects `workspace.activeProjects`
+  config. `--all` bypasses product scope to show all team projects.
+
+### Fixed
+- **`list_projects.py` 400 error** (ENG-474) — state filter was using nested
+  `{type: {nin: [...]}}` instead of direct `StringComparator` `{nin: [...]}`.
+  Both `--active` (started only) and default (excludes completed/canceled) now work.
+- **`list_projects.py --active`** — now correctly filters to only `started` projects
+  instead of being a no-op duplicate of the default behavior.
+- **`assign_milestone.py` error handling** — null-safe check on API response prevents
+  `AttributeError` when GraphQL returns errors.
+
+---
+
+## [0.3.4] — 2026-02-10
+
+### Added
+- **`list_issues.py --milestone` filter** — filter issues by project milestone ID.
+  Get milestone IDs from `list_milestones.py`, then pass to `list_issues.py --milestone <ID>`
+  to see all issues within a specific milestone.
+
+---
+
+## [0.3.3] — 2026-02-10
+
+### Fixed
+- **Shell escaping in `update_description.py`** — descriptions with apostrophes,
+  parentheses, quotes, and other shell metacharacters no longer break when passed
+  via `--text`. Scripts now accept stdin as input, allowing safe heredoc piping:
+  `python3 update_description.py ENG-123 <<'EOF'`
+- **Shell escaping in `comment.py`** — same stdin fallback added. Comment body
+  argument is now optional when piping via stdin.
+
+---
+
+## [0.3.2] — 2026-02-09
+
+### Fixed
+- **API connection reliability** — reduced socket timeout from 30s to 10s and increased
+  max retries from 3 to 5. Resolves intermittent hangs caused by DNS returning unreachable
+  Cloudflare edge IPs. Scripts now fail over to a working IP within seconds instead of
+  waiting 10-30s per attempt.
+- **TimeoutError handling** — retry loop now catches `TimeoutError` in addition to
+  `URLError`, preventing unhandled socket timeouts from crashing scripts.
+
+---
+
+## [0.3.1] — 2026-02-08
+
+### Fixed
+- **`list_issues.py` product scope** — scoping via `activeProjects` and `product.labelIds`
+  now applies regardless of `--active` or `--status` flags. Previously, these flags
+  bypassed product scope entirely, returning all team issues.
+
+### Added
+- **`build_product_scope()` API helper** — new method on `FlyDocsClient` implements the
+  product scope cascade: `activeProjects` → `product.labelIds` → team-wide.
+- **Multiple `activeProjects` support** — `list_issues.py` now uses OR logic when
+  multiple active projects are configured (was only using the first one).
+- **Product label AND filtering** — when `product.labelIds` is set and no `activeProjects`
+  are configured, issues must have ALL specified labels to be included.
+
+---
+
+## [0.3.0] — 2026-02-08
+
+### Added
+- **`update_issue.py` bulk update script** — set multiple fields (priority, estimate,
+  assignee, state, description, comment) in a single API call instead of separate scripts.
+- **`list_issues.py --active` flag** — returns all non-terminal issues (excludes Done,
+  Archived, Canceled, Duplicate). Replaces `status_summary.py`.
+- **`list_issues.py` multi-status support** — comma-separated: `--status READY,IMPLEMENTING,BLOCKED`
+- **`get_issue.py --fields` flag** — `basic` skips comment fetch for faster responses,
+  `full` includes comments (default).
+- **In-process API caching** — issue ID resolution, team members, and active cycle
+  cached within each script invocation to reduce redundant API calls.
+
+### Changed
+- **`transition.py` optimized** — combined state update and cycle assignment into a
+  single `issueUpdate` mutation (was two separate calls for IMPLEMENTING transitions).
+- **Session start efficiency** — single `list_issues.py --active` call replaces
+  per-status queries. Issues grouped by status in response.
+
+### Removed
+- **`status_summary.py`** — retired from cloud mechanism. Use `list_issues.py --active`
+  and group results by the status field instead.
+
+---
+
+## [0.2.1] — 2026-02-07
+
+### Fixed
+- **Commands not fully populating** — changed from additive `cp` to clear-then-copy
+  for `.claude/commands/` and `.cursor/commands/` directories.
+- **`docflow-core.mdc` not cleaned up** — added to deprecated cursor rules list.
+- **Config version not set on fresh install** — fresh install path now sets version
+  in `config.json`.
+- **Template config version mismatch** — template `config.json` was `0.1.0`, now
+  synced with version file.
+
+### Added
+- **`--force` flag** — force update even when versions match.
+- **Old cursor rule directories and commands** added to deprecated cleanup.
+
+---
+
+## [0.2.0] — 2026-02-06
+
+### Added
+- **Scenario-aware setup command** — `/flydocs-setup` rewritten as a comprehensive
+  agent prompt handling three scenarios: New Project, DocFlow Migration, FlyDocs Update.
+  Includes proactive repo scanning for PRDs and existing documentation.
+- **Changelog and version tracking** — `CHANGELOG.md` included in every install.
+  `install.sh --update` now displays what changed between your version and the new one.
+- **Legacy context migration** — `install.sh` safely moves pre-v1.0 separate context
+  files (`overview.md`, `stack.md`, `standards.md`) to a `legacy/` folder. The setup
+  command reads from legacy, consolidates into `project.md`, and cleans up.
+- **Deprecated file cleanup** — `install.sh --update` detects and offers to remove
+  pre-v1.0 artifacts: old skills, rules, hooks, and cursor rules.
+
+### Changed
+- **Version file synced with manifest** — `.flydocs/version` now matches
+  `manifest.json` version field (was out of sync in 0.1.0).
+
+### Removed
+- Orphaned hook scripts: `session-end.py`, `linear-auto-approve.py`
+
+---
+
+## [0.1.0] — 2026-01-15
+
+### Added
+- Initial release of FlyDocs Core
+- Workflow skill (`flydocs-workflow`) with full lifecycle stages
+- Mechanism skills: `flydocs-cloud` (Linear API) and `flydocs-local` (file-based)
+- Premium skills: `flydocs-figma`, `flydocs-estimates`
+- Agent definitions: PM, Implementation, Review, Research
+- 16 slash commands for the full development workflow
+- Hook scripts: auto-approve, prefer-scripts, post-edit, prompt-submit
+- Issue templates: feature, bug, chore, idea
+- Community skill suggestions based on detected stack
+- `install.sh` with fresh install and update modes
+- Remote installation via GitHub App token