@drafthq/draft 3.0.0 → 3.2.0

package/scripts/tools/okf-bundle.sh

@@ -1,141 +0,0 @@
-#!/usr/bin/env bash
-# okf-bundle.sh — make a draft/ context directory an Open Knowledge Format bundle.
-#
-# OKF (Google Cloud, open spec) treats a directory of markdown files with YAML
-# frontmatter as a knowledge bundle: one file per concept, the file path is the
-# concept's identity, concepts cross-link with markdown links, and index.md is
-# the navigable root. Draft's project-doc files already carry the required
-# `type` frontmatter (architecture.md, .ai-context.md, product.md, ...); this
-# tool writes the bundle's root index.md so the whole draft/ tree is a portable,
-# vendor-neutral OKF bundle.
-# https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
-#
-# Writes <dir>/index.md (the OKF bundle-root index, §6/§11) linking every concept
-# file present, the tracks, and the graph sub-bundle (graph/okf/). Validate the
-# result with okf-check.sh (the OKF v0.1 conformance checker).
-#
-# Usage: scripts/tools/okf-bundle.sh [--dir DIR]
-# Exit codes: 0 OK, 1 invocation error, 2 dir missing.
-set -euo pipefail
-
-DIR="draft"
-
-usage() {
-    cat <<'EOF'
-okf-bundle.sh — write the OKF bundle-root index.md for a draft/ context bundle.
-
-Usage:
-  scripts/tools/okf-bundle.sh [--dir DIR]
-
-Flags:
-  --dir DIR  Bundle root (default: draft).
-  --help     Show this help.
-
-Writes <dir>/index.md cross-linking every concept present, the tracks, and the
-graph sub-bundle. Validate conformance with `okf-check.sh --dir <dir>`.
-Exit 0 OK, 1 invocation error, 2 when <dir> is absent.
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        --dir) DIR="$2"; shift 2;;
-        --help|-h) usage; exit 0;;
-        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
-        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
-    esac
-done
-
-[[ -d "$DIR" ]] || { echo "ERROR: --dir '$DIR' is not a directory" >&2; exit 2; }
-
-# Canonical Draft concepts, ordered: "filename|label|expected-type".
-# Each present file is linked from index.md and checked for `type:` under --check.
-CONCEPTS=(
-    ".ai-profile.md|AI Profile|Profile"
-    ".ai-context.md|AI Context Map|ContextMap"
-    "architecture.md|Architecture|Architecture"
-    "product.md|Product|Product"
-    "tech-stack.md|Tech Stack|TechStack"
-    "workflow.md|Workflow|Workflow"
-    "guardrails.md|Guardrails|Guardrails"
-    "service-index.md|Service Index|ServiceIndex"
-)
-
-# read_fm_field FILE FIELD — print a top-level frontmatter scalar (quotes stripped).
-read_fm_field() {
-    awk -v field="$2" '
-        NR==1 { if ($0 != "---") exit; next }
-        /^---[[:space:]]*$/ { exit }
-        {
-            if (index($0, field ":") == 1) {
-                sub("^" field ":[[:space:]]*", "")
-                gsub(/^"|"$/, "")
-                print
-                exit
-            }
-        }
-    ' "$1"
-}
-
-# --- write the bundle root index.md ---
-PROJECT=""
-for probe in architecture.md .ai-context.md product.md .ai-profile.md; do
-    if [[ -f "$DIR/$probe" ]]; then
-        PROJECT="$(read_fm_field "$DIR/$probe" project)"
-        [[ -n "$PROJECT" ]] && break
-    fi
-done
-[[ -n "$PROJECT" && "$PROJECT" != "{PROJECT_NAME}" ]] || PROJECT="$(basename "$(cd "$DIR/.." && pwd)")"
-
-INDEX="$DIR/index.md"
-{
-    # Bundle-root index.md: frontmatter is permitted only to declare okf_version (§11).
-    printf -- '---\n'
-    printf 'okf_version: "0.1"\n'
-    printf -- '---\n\n'
-    printf '# %s — Draft Context Bundle\n\n' "$PROJECT"
-    printf 'Open Knowledge Format (OKF) bundle root. Each concept below is a markdown file with a `type` frontmatter field; the links form the navigable knowledge graph.\n'
-
-    # Context concepts (only if at least one is present)
-    context=""
-    for entry in "${CONCEPTS[@]}"; do
-        IFS='|' read -r fname label expected <<< "$entry"
-        [[ -f "$DIR/$fname" ]] || continue
-        t="$(read_fm_field "$DIR/$fname" type)"
-        [[ -n "$t" ]] || t="$expected"
-        d="$(read_fm_field "$DIR/$fname" description)"
-        desc="${d:-$t concept}"
-        context+="$(printf -- '* [%s](%s) - %s' "$label" "$fname" "$desc")"$'\n'
-    done
-    if [[ -n "$context" ]]; then
-        printf '\n# Context\n\n%s' "$context"
-    fi
-
-    # Tracks
-    if [[ -f "$DIR/tracks.md" || -d "$DIR/tracks" ]]; then
-        printf '\n# Tracks\n\n'
-        [[ -f "$DIR/tracks.md" ]] && printf -- '* [Track Index](tracks.md) - active, completed, and archived tracks\n'
-        if [[ -d "$DIR/tracks" ]]; then
-            for td in "$DIR"/tracks/*/; do
-                [[ -d "$td" ]] || continue
-                id="$(basename "$td")"
-                [[ -f "$td/spec.md" ]] || continue
-                title="$id"
-                if command -v jq >/dev/null 2>&1 && [[ -f "$td/metadata.json" ]]; then
-                    mt="$(jq -r '.title // empty' "$td/metadata.json" 2>/dev/null || true)"
-                    [[ -n "$mt" ]] && title="$mt"
-                fi
-                printf -- '* [%s](tracks/%s/spec.md) - track %s\n' "$title" "$id" "$id"
-            done
-        fi
-    fi
-
-    # Knowledge graph sub-bundle
-    if [[ -f "$DIR/graph/okf/index.md" ]]; then
-        printf '\n# Knowledge graph\n\n'
-        printf -- '* [Graph bundle](graph/okf/index.md) - structural knowledge graph (modules, dependencies, hotspots)\n'
-    fi
-} > "$INDEX"
-
-echo "OKF bundle root written to $INDEX"
-exit 0

package/scripts/tools/okf-check.sh

@@ -1,137 +0,0 @@
-#!/usr/bin/env bash
-# okf-check.sh — validate a directory against the Open Knowledge Format v0.1 spec.
-#
-# Implements the §9 conformance criteria of OKF v0.1
-# (https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):
-#
-#   §9.1  Every non-reserved .md file has a parseable YAML frontmatter block.
-#   §9.2  Every such frontmatter block has a non-empty `type` field.
-#   §9.3  Reserved files follow their structure when present:
-#           index.md  (§6)  — contains NO frontmatter, EXCEPT the bundle-root
-#                             index.md MAY carry frontmatter holding only
-#                             `okf_version` (§11).
-#           log.md    (§7)  — `## ` date headings MUST be ISO 8601 (YYYY-MM-DD).
-#
-# Consumers are required to be permissive, so this checker only enforces the
-# three hard rules above; everything else in the spec is soft guidance.
-#
-# Usage: scripts/tools/okf-check.sh [--dir DIR] [--quiet]
-# Exit codes: 0 conformant, 1 violations found, 2 dir missing.
-set -euo pipefail
-
-DIR="draft"
-QUIET=0
-
-usage() {
-    cat <<'EOF'
-okf-check.sh — validate a directory against Open Knowledge Format v0.1 (§9).
-
-Usage:
-  scripts/tools/okf-check.sh [--dir DIR] [--quiet]
-
-Flags:
-  --dir DIR  Bundle root to validate (default: draft).
-  --quiet    Print only the summary line, not per-file violations.
-  --help     Show this help.
-
-Exit 0 when conformant, 1 when violations are found, 2 when DIR is absent.
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        --dir) DIR="$2"; shift 2;;
-        --quiet) QUIET=1; shift;;
-        --help|-h) usage; exit 0;;
-        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
-        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
-    esac
-done
-
-[[ -d "$DIR" ]] || { echo "ERROR: --dir '$DIR' is not a directory" >&2; exit 2; }
-DIR="${DIR%/}"
-
-# fm_scan FILE -> "STATUS|TYPE|KEYS"  (pipe-delimited; '|' is not IFS-whitespace,
-# so empty TYPE/KEYS fields survive `read` instead of collapsing).
-#   STATUS: nofm (no frontmatter) | ok (closed block) | unterminated
-#   TYPE:   value of the top-level `type:` key, if any
-#   KEYS:   comma-separated top-level frontmatter keys
-fm_scan() {
-    awk '
-        NR==1 { if ($0 != "---") { print "nofm||"; exit } ; inblock=1; next }
-        inblock && /^---[[:space:]]*$/ { print "ok|" type "|" keys; closed=1; exit }
-        inblock {
-            if (match($0, /^[A-Za-z_][A-Za-z0-9_]*:/)) {
-                k = substr($0, 1, RLENGTH-1)
-                keys = keys (keys=="" ? "" : ",") k
-                if (k == "type") {
-                    v = substr($0, RLENGTH+1)
-                    gsub(/^[ \t]+|[ \t]+$/, "", v)
-                    gsub(/^"|"$/, "", v)
-                    type = v
-                }
-            }
-            next
-        }
-        END { if (inblock && !closed) print "unterminated|" type "|" keys }
-    ' "$1"
-}
-
-violations=0
-concepts=0
-reserved=0
-
-report() { # relpath  message
-    violations=$((violations + 1))
-    [[ "$QUIET" == "1" ]] || echo "FAIL  $1: $2" >&2
-}
-
-while IFS= read -r -d '' file; do
-    rel="${file#"$DIR"/}"
-    base="$(basename "$file")"
-
-    case "$base" in
-        index.md)
-            reserved=$((reserved + 1))
-            IFS='|' read -r status _ keys < <(fm_scan "$file")
-            if [[ "$status" != "nofm" ]]; then
-                if [[ "$rel" == "index.md" ]]; then
-                    # Bundle-root index.md: frontmatter allowed, but only okf_version (§11).
-                    IFS=',' read -ra ks <<< "$keys"
-                    for k in "${ks[@]}"; do
-                        [[ -z "$k" || "$k" == "okf_version" ]] && continue
-                        report "$rel" "root index.md frontmatter may only hold 'okf_version' (§11); found '$k'"
-                    done
-                else
-                    report "$rel" "index.md must not contain frontmatter (§6)"
-                fi
-            fi
-            ;;
-        log.md)
-            reserved=$((reserved + 1))
-            while IFS= read -r h; do
-                if ! [[ "$h" =~ ^##[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2} ]]; then
-                    report "$rel" "log.md date heading not ISO 8601 (§7): '$h'"
-                fi
-            done < <(grep -E '^## ' "$file" 2>/dev/null || true)
-            ;;
-        *)
-            concepts=$((concepts + 1))
-            IFS='|' read -r status type _ < <(fm_scan "$file")
-            case "$status" in
-                nofm)         report "$rel" "missing YAML frontmatter block (§9.1)";;
-                unterminated) report "$rel" "unterminated frontmatter block — no closing '---' (§9.1)";;
-                ok)
-                    [[ -n "$type" ]] || report "$rel" "frontmatter missing required non-empty 'type' (§9.2)"
-                    ;;
-            esac
-            ;;
-    esac
-done < <(find "$DIR" -type f -name '*.md' -print0 | sort -z)
-
-if [[ "$violations" -eq 0 ]]; then
-    echo "OKF v0.1 conformant — $concepts concept file(s), $reserved reserved file(s), 0 violations. ($DIR)"
-    exit 0
-fi
-echo "OKF v0.1 NON-CONFORMANT — $violations violation(s) across $concepts concept + $reserved reserved file(s). ($DIR)" >&2
-exit 1

package/scripts/tools/okf-emit.sh

@@ -1,161 +0,0 @@
-#!/usr/bin/env bash
-# okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
-#
-# OKF is an open, vendor-neutral spec (Google Cloud): a directory of markdown
-# files with YAML frontmatter, one file per concept, where the file path is the
-# concept's identity and concepts cross-link with normal markdown links. The
-# only required frontmatter field is `type`. This makes Draft's knowledge graph
-# portable — consumable by any OKF reader (visualizers, catalogs, other agents).
-# https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
-#
-# Reads a graph snapshot's architecture.json and writes a conformant bundle:
-#   index.md            type: Repository — bundle root + progressive disclosure
-#   modules/<slug>.md   type: Module     — one concept per package, cross-linked
-#
-# Degrades gracefully: with no packages/boundaries in the snapshot it still emits
-# index.md (counts, languages, hotspots) and an empty modules/ directory.
-#
-# Usage: scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
-# Exit codes: 0 OK, 1 invocation error, 2 snapshot/architecture.json unavailable.
-set -euo pipefail
-
-REPO="."
-SNAPSHOT=""
-OUT=""
-
-usage() {
-    cat <<'EOF'
-okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
-
-Usage:
-  scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
-
-Flags:
-  --repo DIR      Repository root (default: cwd).
-  --snapshot DIR  Snapshot dir holding architecture.json (default: <repo>/draft/graph).
-  --out DIR       Bundle output dir (default: <snapshot>/okf).
-  --help          Show this help.
-
-Writes index.md + modules/<slug>.md (OKF v0.1). Exit 0 on success, 2 when no
-architecture.json is available (nothing emitted).
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --snapshot) SNAPSHOT="$2"; shift 2;;
-        --out) OUT="$2"; shift 2;;
-        --help|-h) usage; exit 0;;
-        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
-        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
-    esac
-done
-
-[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
-REPO_ABS="$(cd "$REPO" && pwd)"
-SNAP="${SNAPSHOT:-$REPO_ABS/draft/graph}"
-ARCH="$SNAP/architecture.json"
-OUT="${OUT:-$SNAP/okf}"
-
-command -v jq >/dev/null 2>&1 || { echo "jq required for OKF emit" >&2; exit 2; }
-[[ -f "$ARCH" ]] || { echo "no architecture.json at $ARCH — nothing to emit" >&2; exit 2; }
-
-# slugify a concept name into a filesystem- and link-safe identifier.
-slug() {
-    local s
-    s="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]' \
-        | sed -e 's#[^a-z0-9]\{1,\}#-#g' -e 's#^-##' -e 's#-$##')"
-    [[ -n "$s" ]] || s="module"
-    printf '%s' "$s"
-}
-
-# escape a value for a YAML double-quoted scalar.
-yesc() {
-    local s="$1"
-    s="${s//\\/\\\\}"
-    s="${s//\"/\\\"}"
-    printf '%s' "$s"
-}
-
-TS="$(date -Iseconds 2>/dev/null || date)"
-PROJECT="$(jq -r '.project // "repository"' "$ARCH")"
-TOTAL_NODES="$(jq -r '.total_nodes // 0' "$ARCH")"
-TOTAL_EDGES="$(jq -r '.total_edges // 0' "$ARCH")"
-
-PKGS="$(jq -r '.packages[]? | [.name, (.node_count//0), (.fan_in//0), (.fan_out//0)] | @tsv' "$ARCH")"
-BOUNDS="$(jq -r '.boundaries[]? | [.from, .to, (.call_count//0)] | @tsv' "$ARCH")"
-
-mkdir -p "$OUT/modules"
-
-# --- One concept file per package, cross-linked via boundaries ---
-PKG_COUNT=0
-if [[ -n "$PKGS" ]]; then
-    while IFS=$'\t' read -r name nc fi fo; do
-        [[ -n "$name" ]] || continue
-        PKG_COUNT=$((PKG_COUNT + 1))
-        s="$(slug "$name")"
-        {
-            printf -- '---\n'
-            printf 'type: Module\n'
-            printf 'title: "%s"\n' "$(yesc "$name")"
-            printf 'description: "Code module %s: %s nodes, fan-in %s, fan-out %s."\n' \
-                "$(yesc "$name")" "$nc" "$fi" "$fo"
-            printf 'tags: [module, knowledge-graph]\n'
-            printf 'timestamp: "%s"\n' "$TS"
-            printf -- '---\n\n'
-            printf '# %s\n\n' "$name"
-            printf 'Structural module derived from the knowledge graph. Nodes: %s, fan-in: %s, fan-out: %s.\n' \
-                "$nc" "$fi" "$fo"
-
-            # Depends on (outbound boundaries)
-            outs="$(awk -F'\t' -v n="$name" '$1==n && $2!="" {print $2"\t"$3}' <<< "$BOUNDS")"
-            if [[ -n "$outs" ]]; then
-                printf '\n## Depends on\n\n'
-                while IFS=$'\t' read -r to cc; do
-                    [[ -n "$to" ]] || continue
-                    printf -- '- [%s](%s.md) — %s call(s)\n' "$to" "$(slug "$to")" "$cc"
-                done <<< "$outs"
-            fi
-
-            # Depended on by (inbound boundaries)
-            ins="$(awk -F'\t' -v n="$name" '$2==n && $1!="" {print $1"\t"$3}' <<< "$BOUNDS")"
-            if [[ -n "$ins" ]]; then
-                printf '\n## Depended on by\n\n'
-                while IFS=$'\t' read -r from cc; do
-                    [[ -n "$from" ]] || continue
-                    printf -- '- [%s](%s.md) — %s call(s)\n' "$from" "$(slug "$from")" "$cc"
-                done <<< "$ins"
-            fi
-        } > "$OUT/modules/$s.md"
-    done <<< "$PKGS"
-fi
-
-# --- Bundle index.md (reserved file: no frontmatter, §6 progressive disclosure) ---
-{
-    printf '# %s\n\n' "$PROJECT"
-    printf 'Open Knowledge Format bundle generated by Draft from the codebase-memory-mcp knowledge graph. Nodes: %s, edges: %s, modules: %s.\n' \
-        "$TOTAL_NODES" "$TOTAL_EDGES" "$PKG_COUNT"
-
-    langs="$(jq -r '.languages[]? | "* \(.language) - \(.file_count) file(s)"' "$ARCH")"
-    if [[ -n "$langs" ]]; then
-        printf '\n# Languages\n\n%s\n' "$langs"
-    fi
-
-    if [[ "$PKG_COUNT" -gt 0 ]]; then
-        printf '\n# Modules\n\n'
-        while IFS=$'\t' read -r name nc fi fo; do
-            [[ -n "$name" ]] || continue
-            printf -- '* [%s](modules/%s.md) - %s nodes, fan-in %s, fan-out %s\n' \
-                "$name" "$(slug "$name")" "$nc" "$fi" "$fo"
-        done < <(printf '%s\n' "$PKGS" | sort)
-    fi
-
-    hot="$(jq -r '.hotspots[:10][]? | "* \(.name) - fan-in \(.fan_in)"' "$ARCH")"
-    if [[ -n "$hot" ]]; then
-        printf '\n# Top hotspots\n\n%s\n' "$hot"
-    fi
-} > "$OUT/index.md"
-
-echo "OKF bundle written to $OUT (modules=$PKG_COUNT)"
-exit 0