@flydocs/cli 0.6.0-alpha.24 → 0.6.0-alpha.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.6.0-alpha.24",
+  "version": "0.6.0-alpha.26",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

package/template/.claude/hooks/session-start.py

@@ -84,7 +84,17 @@ def get_active_issue_context() -> str | None:
 
 
 def get_config_freshness() -> str | None:
-    """Warn if validation cache is stale or missing."""
+    """Warn if validation cache is stale or missing (v1 configs)."""
+    # v2 configs use get_config_freshness_v2() instead
+    config_file = Path('.flydocs/config.json')
+    if config_file.exists():
+        try:
+            config = json.loads(config_file.read_text())
+            if config.get('configFormat') == 2:
+                return None  # Skip v1 check for v2 configs
+        except (json.JSONDecodeError, OSError):
+            pass
+
     cache_file = Path('.flydocs/validation-cache.json')
     if not cache_file.exists():
         return None
@@ -102,6 +112,104 @@ def get_config_freshness() -> str | None:
     return None
 
 
+def get_config_freshness_v2() -> str | None:
+    """Check config freshness via config/check endpoint (v2 configs only, FLY-540)."""
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+
+    try:
+        config = json.loads(config_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    if config.get('configFormat') != 2 or config.get('tier') != 'cloud':
+        return None
+
+    # Resolve API key: env var > global credentials
+    api_key = os.environ.get('FLYDOCS_API_KEY')
+    if not api_key:
+        cred_file = Path.home() / '.flydocs' / 'credentials'
+        if cred_file.exists():
+            try:
+                cred = json.loads(cred_file.read_text())
+                api_key = cred.get('apiKey')
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    if not api_key:
+        return None
+
+    # Call config/check — lightweight, ~50ms
+    base_url = os.environ.get('FLYDOCS_RELAY_URL', 'https://app.flydocs.ai/api/relay').rstrip('/')
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            f'{base_url}/config/check',
+            headers={
+                'Authorization': f'Bearer {api_key}',
+                'Accept': 'application/json',
+            },
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode('utf-8'))
+    except Exception:
+        # Server unreachable — silently continue, never block a session
+        return None
+
+    if data.get('needsSync'):
+        stale_fields: list[str] = []
+        local_config_version = config.get('configVersion', 0)
+        if data.get('configVersion', 0) > local_config_version:
+            stale_fields.append('config')
+        if data.get('templateVersion', 0) > 0:
+            stale_fields.append('templates')
+        if data.get('contextVersion', 0) > 0:
+            stale_fields.append('context')
+        detail = f' ({", ".join(stale_fields)})' if stale_fields else ''
+        return f'Config updated{detail} — run `flydocs sync`'
+
+    return None
+
+
+def check_skills_manifest() -> str | None:
+    """Alert-mode skills manifest validation (FLY-541)."""
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+
+    try:
+        config = json.loads(config_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    expected = config.get('skills', {}).get('installed', [])
+    if not expected:
+        return None
+
+    skills_dir = Path('.claude/skills')
+    if not skills_dir.is_dir():
+        return f'Skills directory missing — run `flydocs sync`'
+
+    # Check for installed directories
+    try:
+        installed = {d.name for d in skills_dir.iterdir() if d.is_dir()}
+    except OSError:
+        return None
+
+    expected_set = set(expected)
+    missing = expected_set - installed
+    unexpected = installed - expected_set
+
+    warnings: list[str] = []
+    if missing:
+        warnings.append(f'Missing skills: {", ".join(sorted(missing))} — run `flydocs sync`')
+    if unexpected:
+        warnings.append(f'Unexpected skills: {", ".join(sorted(unexpected))}')
+
+    return ' | '.join(warnings) if warnings else None
+
+
 def main() -> None:
     """Main hook execution."""
     try:
@@ -129,6 +237,14 @@ def main() -> None:
     if freshness:
         parts.append(freshness)
 
+    freshness_v2 = get_config_freshness_v2()
+    if freshness_v2:
+        parts.append(freshness_v2)
+
+    skills_warning = check_skills_manifest()
+    if skills_warning:
+        parts.append(skills_warning)
+
     if not parts:
         print('{}')
         sys.exit(0)

package/template/.claude/skills/flydocs-workflow/reference/service-descriptor-schema.md

@@ -14,13 +14,14 @@ The service descriptor serves two roles from a single file:
   where things are: entry points, shared types, build system, package boundaries.
   Not exported cross-repo.
 
-Generated by the user's coding agent during `/flydocs-setup` Phase 1.5.
+Generated by the user's coding agent during `/flydocs-setup` Phase 1.5, or by the
+server-side AI scanning pipeline (v2).
 
 ## Schema
 
 ```typescript
 interface ServiceDescriptor {
-  version: 1;
+  version: 1 | 2;
   name: string; // Human-readable service name
   repoSlug: string; // owner/repo format (matches workspace.repoSlug)
   purpose: string; // One-sentence description of what this service does
@@ -32,6 +33,10 @@ interface ServiceDescriptor {
 
   // Intra-repo orientation (what THIS repo's agent uses)
   structure: ServiceStructure;
+
+  // v2 fields (present when version is 2, optional for backward compat)
+  generatedBy?: "server" | "agent"; // Who generated this descriptor
+  generatedAt?: string; // ISO 8601 timestamp of generation
 }
 
 interface ApiSurface {
@@ -63,12 +68,16 @@ interface PackageInfo {
 
 ## Field Notes
 
-- `version` is always `1`. Will increment on breaking schema changes.
+- `version` is `1` (agent-generated, legacy) or `2` (supports server generation).
+  All consumers accept both versions. The v2 fields are additive — v1 descriptors
+  remain valid and fully functional.
 - `repoSlug` must match the slug registered in the workspace dashboard.
 - `structure` is local-only — not pushed to relay or included in workspace composite.
 - `apis` and `dependencies` create PROVIDES/CONSUMES edges in the graph.
 - `stack` is a flat array of lowercase identifiers (framework names, languages).
-- Agent scans the codebase to populate all fields during setup Phase 1.5.
+- `generatedBy` distinguishes server-generated (AI scanning pipeline) from
+  agent-generated (local `/flydocs-setup`) descriptors. Absent on v1 descriptors.
+- `generatedAt` tracks freshness for server-generated descriptors. ISO 8601 format.
 
 ## Examples
 

package/template/.claude/skills/flydocs-workflow/scripts/graph_build.py

@@ -219,7 +219,7 @@ def scan_service_descriptor(root):
     except (json.JSONDecodeError, OSError):
         return nodes, edges
 
-    if data.get("version") != 1:
+    if data.get("version") not in (1, 2):
         return nodes, edges
 
     repo_slug = data.get("repoSlug", "")
@@ -290,7 +290,7 @@ def scan_sibling_descriptors(root):
         except (json.JSONDecodeError, OSError):
             continue
 
-        if data.get("version") != 1:
+        if data.get("version") not in (1, 2):
             continue
 
         repo_slug = data.get("repoSlug", "")

package/template/.flydocs/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.24",
+  "version": "0.6.0-alpha.26",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.24
+0.6.0-alpha.26

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.24",
+  "version": "0.6.0-alpha.26",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",