@webship.co/workspace-graph 1.0.0-alpha1 → 1.0.0-beta1

package/scripts/functions/fun-graphs.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+
+# The graphs workspace: every project's knowledge graph, one directory per project at
+# graphs/<workspace>/<project>/. cmd-tools-graphify.sh builds them and moves them here;
+# this command is what you do with them afterwards.
+#
+# The graph is NOT kept inside the project on purpose — it is tens of MB, Leiden clustering is not
+# bit-stable so it re-diffs entirely on every rebuild, and half the projects worth mapping are
+# repositories we ship.
+
+# Resolve a name to one or more <workspace>/<project> directories INSIDE the store.
+#
+# Every path this returns is checked, because the caller deletes what it is handed: a name is
+# refused if it contains `..`, if it does not resolve to exactly two segments under the store, or if
+# the directory holds no graph.json. Without that, `-a remove '../modules/toc_api'` resolved to a
+# real project checkout and deleted it — verified, then fixed.
+function graphs_resolve() {
+  local wanted="$1" base dir real;
+  base="$(cd "${WORKSPACE_ROOT}/graphs" 2>/dev/null && pwd -P)" || return 0 ;
+
+  # A candidate is emitted only if it survives containment, shape and content checks.
+  _graphs_emit() {
+    local candidate="$1" resolved;
+    resolved="$(realpath -m "${candidate}" 2>/dev/null)" || return 0 ;
+    case "${resolved}" in
+      "${base}/"*) ;;
+      *) return 0 ;;
+    esac
+    # Exactly <workspace>/<project> under the store, and it must actually hold a graph.
+    [ "$(printf '%s' "${resolved#${base}/}" | tr -cd '/' | wc -c)" -eq 1 ] || return 0 ;
+    [ -f "${resolved}/graph.json" ] || return 0 ;
+    printf '%s\n' "${resolved}";
+  }
+
+  case "${wanted}" in
+    *..*) return 0 ;;
+  esac
+
+  if [ "${wanted}" == '_all_' ] ; then
+    while read -r dir ; do
+      [ -n "${dir}" ] && _graphs_emit "${dir}" ;
+    done <<< "$(find "${base}" -mindepth 2 -maxdepth 2 -type d 2>/dev/null | sort)"
+    return 0 ;
+  fi
+
+  case "${wanted}" in
+    */*) _graphs_emit "${base}/${wanted}" ;;
+    *)   # A bare project name can match in two workspaces; the caller decides what to do with that.
+         while read -r dir ; do
+           [ -n "${dir}" ] && _graphs_emit "${dir}" ;
+         done <<< "$(find "${base}" -mindepth 2 -maxdepth 2 -type d -name "${wanted}" 2>/dev/null | sort)" ;;
+  esac
+}
+
+function graphs_list() {
+  local base="${WORKSPACE_ROOT}/graphs" dir ws project nodes links size;
+
+  if [ -z "$(graphs_resolve "${GRAPH_NAME}")" ] ; then
+    echo "No graphs yet. Build one from the project's workspace folder:";
+    echo "  cd ${WORKSPACE_ROOT}/<workspace> && bash cmd-tools-graphify.sh <project>";
+    return 0 ;
+  fi
+
+  printf '%-46s %8s %8s %9s  %s\n' "GRAPH" "NODES" "EDGES" "SIZE" "PROJECT";
+  while read -r dir ; do
+    [ -n "${dir}" ] || continue ;
+    ws="$(basename "$(dirname "${dir}")")";
+    project="$(basename "${dir}")";
+    read -r nodes links <<< "$(python3 -c "
+import json
+try:
+    d = json.load(open('${dir}/graph.json'))
+    print(len(d.get('nodes', [])), len(d.get('links', d.get('edges', []))))
+except Exception:
+    print('?', '?')
+" 2>/dev/null)";
+    size="$(du -sh "${dir}" 2>/dev/null | cut -f1)";
+    printf '%-46s %8s %8s %9s  %s\n' "${ws}/${project}" "${nodes}" "${links}" "${size}" \
+      "$([ -d "${WORKSPACE_ROOT}/${ws}/${project}" ] && echo present || echo "gone — safe to remove")";
+  done <<< "$(graphs_resolve "${GRAPH_NAME}")"
+}
+
+# Sweep up graphs left inside projects by an older build, or by graphify run by hand.
+function graphs_collect() {
+  local out ws project dest moved=0;
+
+  while read -r out ; do
+    [ -n "${out}" ] || continue ;
+    ws="$(basename "$(dirname "$(dirname "${out}")")")";
+    project="$(basename "$(dirname "${out}")")";
+    dest="${WORKSPACE_ROOT}/graphs/${ws}/${project}";
+    if [ -d "${dest}" ] ; then
+      echo "  ${ws}/${project}: already in the graphs workspace — left where it is, delete the copy in the project yourself if it is stale.";
+      continue ;
+    fi
+    mkdir -p "$(dirname "${dest}")" ;
+    if mv "${out}" "${dest}" ; then
+      echo "  moved ${ws}/${project}";
+      moved=$((moved + 1));
+      # That project's CLAUDE.md still tells a session the graph is in graphify-out/ and gives
+      # commands with no --graph, which now error. Rewrite the note against the new location.
+      PROJECT_NAME="${project}" doc_name="${ws}" \
+        graphify_write_project_note "$(dirname "${out}")" "${dest}" > /dev/null 2>&1 ;
+    fi
+  done <<< "$(find "${WORKSPACE_ROOT}" -mindepth 3 -maxdepth 3 -name graphify-out -type d 2>/dev/null | sort)"
+
+  # The YAML mirror is a build input, never a result.
+  find "${WORKSPACE_ROOT}" -mindepth 3 -maxdepth 3 -name graphify-yaml -type d -exec rm -rf {} + 2>/dev/null ;
+
+  echo "";
+  echo "Collected ${moved} graph(s) into ${WORKSPACE_ROOT}/graphs/.";
+}
+
+function graphs_remove() {
+  local matches count dir;
+
+  # Deleting everything must be asked for by name, never be the default. GRAPH_NAME defaults to
+  # _all_, so without this a bare `-a remove` deleted whichever graph sorted first.
+  if [ "${GRAPH_NAME}" == '_all_' ] ; then
+    echo "Name the graph to remove: bash cmd-tools-graphs.sh <workspace>/<project> -a remove";
+    echo "  (--graphs-action list shows them)";
+    return 1 ;
+  fi
+
+  matches="$(graphs_resolve "${GRAPH_NAME}")";
+  count="$(printf '%s' "${matches}" | grep -c . )";
+
+  if [ "${count}" -eq 0 ] ; then
+    echo "No graph matches '${GRAPH_NAME}' inside ${WORKSPACE_ROOT}/graphs.";
+    echo "  Run with --graphs-action list to see them.";
+    return 1 ;
+  fi
+  # Ambiguity is refused rather than resolved by sort order: the same project name can exist in two
+  # workspaces, and this is the one action that cannot be undone.
+  if [ "${count}" -gt 1 ] ; then
+    echo "'${GRAPH_NAME}' matches ${count} graphs — name the workspace too:";
+    while read -r dir ; do printf '  %s\n' "${dir#${WORKSPACE_ROOT}/graphs/}"; done <<< "${matches}"
+    return 1 ;
+  fi
+
+  dir="${matches}";
+  rm -rf "${dir}" ;
+  echo "Deleted ${dir#${WORKSPACE_ROOT}/graphs/}. Rebuild it with cmd-tools-graphify.sh in its workspace folder.";
+}
+
+# Serve one graph to the Claude Code CLI over MCP.
+#
+# graphify ships its own MCP server (`graphify-mcp`, i.e. python -m graphify.serve) with ten tools:
+# query_graph, get_node, get_neighbors, shortest_path, get_community, god_nodes, graph_stats,
+# list_prs, get_pr_impact, triage_prs. Registered on **stdio**, so there is no port to keep open
+# and no daemon to remember: the CLI starts it when a session needs it and stops it after.
+function graphs_mcp() {
+  local dir ws project name graph;
+  dir="$(graphs_resolve "${GRAPH_NAME}" | head -1)";
+
+  if [ "${GRAPH_NAME}" == '_all_' ] ; then
+    echo "Name the graph: bash cmd-tools-graphs.sh <workspace>/<project> --graphs-action ${GRAPHS_ACTION}";
+    return 1 ;
+  fi
+  if [ -z "${dir}" ] || [ ! -f "${dir}/graph.json" ] ; then
+    echo "No graph for '${GRAPH_NAME}'. Build it first from its workspace folder.";
+    return 1 ;
+  fi
+
+  ws="$(basename "$(dirname "${dir}")")";
+  project="$(basename "${dir}")";
+  name="graph-${ws}-${project}";
+  graph="${dir}/graph.json";
+
+  case "${GRAPHS_ACTION}" in
+    mcp-register)
+      # `command -v` is not enough: the entry point is installed whether or not the mcp dependency
+      # is, and without it the server dies at import time — which the CLI reports only as
+      # "Connection closed". Prove the import instead.
+      if ! graphify-mcp --help > /dev/null 2>&1 ; then
+        echo "graphify-mcp cannot run — its mcp dependency is missing or too new (graphify needs mcp<2).";
+        echo "  Fix it with: uv tool install --force \"graphifyy[sql]==${GRAPHIFY_VERSION:-0.9.28}\" --with \"mcp<2\"";
+        return 1 ;
+      fi
+      claude mcp add --scope user "${name}" -- graphify-mcp "${graph}" || return 1 ;
+      echo "";
+      echo "Registered ${name} with the Claude Code CLI (stdio, no port).";
+      echo "  Open a NEW session to see its tools: query_graph, get_node, get_neighbors,";
+      echo "  shortest_path, get_community, god_nodes, graph_stats, list_prs, get_pr_impact, triage_prs.";
+      echo "  Rebuilding the graph needs no re-registration — the file path does not change.";
+      ;;
+    mcp-unregister)
+      claude mcp remove --scope user "${name}" && echo "Removed ${name} from the Claude Code CLI." ;
+      ;;
+    serve)
+      echo "Serving ${ws}/${project} over MCP on stdio — Ctrl+C to stop.";
+      exec graphify-mcp "${graph}" ;
+      ;;
+  esac
+}
+
+function graphs_command() {
+  case "${GRAPHS_ACTION}" in
+    list)    graphs_list ;;
+    collect) graphs_collect ;;
+    remove)  graphs_remove ;;
+    mcp-register|mcp-unregister|serve) graphs_mcp ;;
+    *)       echo "Unknown action '${GRAPHS_ACTION}'." ; return 1 ;;
+  esac
+}

package/scripts/functions/fun-obsidian.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+
+# Turn a project's knowledge graph into an Obsidian vault.
+#
+# The graph is already the hard part: `graphify` parses the code and writes
+# graphs/<workspace>/<project>/graph.json — the entities and the relations between
+# them. Obsidian is a reader for exactly that shape, so this converts rather than
+# re-parses. Parsing the tree a second time would cost the same minutes again and
+# could disagree with the graph the rest of the menu shows.
+#
+# What it writes, next to the graph in graphs/<workspace>/<project>/obsidian/:
+#
+#   <project>.md          the index — every entity, grouped by the cluster graphify found
+#   notes/<entity>.md     one note per node: frontmatter, then a [[wikilink]] per relation
+#   <project>.canvas      JSON Canvas 1.0, so Obsidian's Canvas opens the actual map
+#   .obsidian/            enough config that Obsidian opens the vault without asking
+#
+# The wikilinks are the point. Obsidian builds its own graph view, backlinks and
+# unlinked-mentions from them, so a graph that was a static picture becomes something
+# you can walk — and the notes are plain markdown, readable without Obsidian at all.
+#
+# JSON Canvas 1.0: https://jsoncanvas.org/spec/1.0/
+
+# Where a project's vault lives: inside its graph store, because it is made from the
+# graph and is thrown away with it.
+function obsidian_vault_dir() {
+  printf '%s' "${WORKSPACE_ROOT}/graphs/${1}/${2}/obsidian";
+}
+
+# Build the vault from the graph.
+function obsidian_project() {
+  local ws="${doc_name}" project="${PROJECT_NAME}";
+  local store="${WORKSPACE_ROOT}/graphs/${ws}/${project}";
+  local graph="${store}/graph.json";
+  local vault; vault=$(obsidian_vault_dir "${ws}" "${project}");
+
+  if [ ! -f "${graph}" ] ; then
+    echo "No graph for ${ws}/${project} yet." ;
+    echo "Build one first:  bash cmd-tools-graphify.sh ${project}" ;
+    return 1 ;
+  fi
+
+  if ! command -v python3 > /dev/null 2>&1 ; then
+    echo "python3 is needed to read the graph — not found." ;
+    return 1 ;
+  fi
+
+  echo "*---------------------------------------------------------------------*";
+  echo "  Obsidian vault for ${ws}/${project}";
+  echo "*---------------------------------------------------------------------*";
+  echo "  graph   ${graph}";
+  echo "  vault   ${vault}";
+  echo "";
+
+  # Written to a sibling directory and swapped in, so an interrupted run never leaves
+  # a half-written vault where Obsidian would open it.
+  local tmp="${vault}.building";
+  rm -rf "${tmp}" ;
+  mkdir -p "${tmp}" ;
+
+  if ! MAX_CANVAS_NODES="${MAX_CANVAS_NODES:-300}" python3 - "${graph}" "${tmp}" "${project}" "${ws}" <<'PYEOF'
+import json, os, re, sys, unicodedata
+from collections import defaultdict
+
+graph_path, out, project, workspace = sys.argv[1:5]
+max_canvas = int(os.environ.get('MAX_CANVAS_NODES', '300'))
+
+with open(graph_path, encoding='utf-8') as fh:
+    graph = json.load(fh)
+
+nodes = graph.get('nodes') or []
+links = graph.get('links') or []
+
+if not nodes:
+    print('  The graph has no nodes — nothing to write.')
+    sys.exit(2)
+
+# ---------------------------------------------------------------- note names
+# A node id is whatever the parser found: it can carry /, :, #, characters Windows
+# refuses and characters Obsidian reads as link syntax. Sanitise, then de-duplicate,
+# because two different ids can flatten to the same name and a collision would make
+# one note silently overwrite the other.
+ILLEGAL = re.compile(r'[\\/:*?"<>|\[\]#^]+')
+
+def note_name(raw):
+    name = unicodedata.normalize('NFC', str(raw)).strip()
+    name = ILLEGAL.sub('-', name).strip(' .-')
+    return name[:120] or 'unnamed'
+
+names, taken = {}, {}
+for n in nodes:
+    nid = n.get('id')
+    if nid is None:
+        continue
+    base = note_name(n.get('label') or nid)
+    key = base.lower()
+    if key in taken:
+        taken[key] += 1
+        base = f'{base} ({taken[key]})'
+    else:
+        taken[key] = 1
+    names[nid] = base
+
+# --------------------------------------------------------------------- edges
+out_edges = defaultdict(list)
+in_edges = defaultdict(list)
+for e in links:
+    s, t = e.get('source'), e.get('target')
+    if s in names and t in names:
+        rel = str(e.get('relation') or 'relates to')
+        out_edges[s].append((t, rel))
+        in_edges[t].append((s, rel))
+
+by_id = {n['id']: n for n in nodes if n.get('id') in names}
+
+def yaml_str(v):
+    s = str(v).replace('"', "'")
+    return f'"{s}"'
+
+# --------------------------------------------------------------------- notes
+notes_dir = os.path.join(out, 'notes')
+os.makedirs(notes_dir, exist_ok=True)
+
+for nid, name in names.items():
+    n = by_id[nid]
+    fm = ['---']
+    fm.append(f'title: {yaml_str(n.get("label") or nid)}')
+    tags = ['graphify']
+    ftype = n.get('file_type')
+    if ftype:
+        tags.append(re.sub(r'[^a-z0-9_-]+', '-', str(ftype).lower()))
+    fm.append('tags: [' + ', '.join(tags) + ']')
+    if n.get('source_file'):
+        fm.append(f'source_file: {yaml_str(n["source_file"])}')
+    if n.get('source_location'):
+        fm.append(f'source_location: {yaml_str(n["source_location"])}')
+    if n.get('community') is not None:
+        fm.append(f'cluster: {n["community"]}')
+    fm.append(f'project: {yaml_str(project)}')
+    fm.append(f'workspace: {yaml_str(workspace)}')
+    fm.append('---')
+
+    body = [f'# {n.get("label") or nid}', '']
+    where = n.get('source_file')
+    if where:
+        loc = n.get('source_location')
+        body.append(f'`{where}`' + (f' — {loc}' if loc else ''))
+        body.append('')
+
+    outs = sorted(out_edges.get(nid, []), key=lambda x: (x[1], names[x[0]]))
+    if outs:
+        body.append('## Points at')
+        body.append('')
+        for tgt, rel in outs:
+            body.append(f'- {rel} → [[{names[tgt]}]]')
+        body.append('')
+
+    ins = sorted(in_edges.get(nid, []), key=lambda x: (x[1], names[x[0]]))
+    if ins:
+        # Obsidian computes backlinks itself, but only from links that exist in the
+        # text. Writing the incoming side too means the relation is readable from
+        # either end, and it survives being read outside Obsidian.
+        body.append('## Pointed at by')
+        body.append('')
+        for src, rel in ins:
+            body.append(f'- [[{names[src]}]] → {rel}')
+        body.append('')
+
+    body.append(f'---')
+    body.append(f'Part of [[{project}]].')
+
+    with open(os.path.join(notes_dir, f'{name}.md'), 'w', encoding='utf-8') as fh:
+        fh.write('\n'.join(fm) + '\n\n' + '\n'.join(body) + '\n')
+
+# --------------------------------------------------------------------- index
+clusters = defaultdict(list)
+for nid, name in names.items():
+    clusters[by_id[nid].get('community', 0)].append(name)
+
+index = ['---', f'title: {yaml_str(project)}', 'tags: [graphify, index]', '---', '',
+         f'# {project}', '',
+         f'The knowledge graph of `{workspace}/{project}`, as notes: '
+         f'**{len(names)} entities**, **{len(links)} relations**, '
+         f'in **{len(clusters)} clusters**.', '',
+         f'Open `{project}.canvas` for the map. Every note links to what it points at, so '
+         'Obsidian\'s own graph view, backlinks and unlinked mentions all work.', '']
+for c in sorted(clusters, key=lambda k: (str(type(k)), k)):
+    index.append(f'## Cluster {c}')
+    index.append('')
+    for name in sorted(clusters[c]):
+        index.append(f'- [[{name}]]')
+    index.append('')
+with open(os.path.join(out, f'{note_name(project)}.md'), 'w', encoding='utf-8') as fh:
+    fh.write('\n'.join(index))
+
+# -------------------------------------------------------------------- canvas
+# JSON Canvas 1.0. Laid out deterministically — grid within cluster, clusters in a
+# grid — because the vault is stored and a random layout would diff in full on
+# every rebuild.
+NODE_W, NODE_H, GAP_X, GAP_Y = 260, 60, 320, 110
+PRESET = ['1', '2', '3', '4', '5', '6']
+
+ranked = sorted(names, key=lambda i: (-len(out_edges.get(i, [])) - len(in_edges.get(i, [])), names[i]))
+shown = ranked[:max_canvas]
+shown_set = set(shown)
+
+canvas_nodes, canvas_edges, canvas_id = [], [], {}
+grouped = defaultdict(list)
+for nid in shown:
+    grouped[by_id[nid].get('community', 0)].append(nid)
+
+# Clusters are packed into ROWS rather than laid end to end. Sixteen clusters in one line
+# made a canvas 13,000 wide and 440 tall: fitted to a screen that is an eight-fold shrink,
+# and every label goes sub-pixel. Wrapping at a target width keeps the map roughly the
+# shape of the thing looking at it.
+MARGIN = 160
+blocks = []
+for c in sorted(grouped, key=lambda k: str(k)):
+    members = sorted(grouped[c], key=lambda i: names[i])
+    cols = max(1, round(len(members) ** 0.5))
+    rows = (len(members) + cols - 1) // cols
+    blocks.append((c, members, cols, cols * GAP_X, rows * GAP_Y))
+
+# Aim for a 16:10-ish sheet: wrap once a row is wider than the square root of the total
+# area, stretched by that ratio.
+area = sum(w * h for _, _, _, w, h in blocks) or 1
+target_w = max(max((w for _, _, _, w, _ in blocks), default=GAP_X), int((area ** 0.5) * 1.6))
+
+cx = cy = row_h = 0
+for ci, (c, members, cols, bw, bh) in enumerate(blocks):
+    if cx > 0 and cx + bw > target_w:
+        cx = 0
+        cy += row_h + MARGIN
+        row_h = 0
+    for i, nid in enumerate(members):
+        cid = f'n{len(canvas_nodes)}-{re.sub(r"[^A-Za-z0-9]", "", str(nid))[:24] or "x"}'
+        canvas_id[nid] = cid
+        canvas_nodes.append({
+            'id': cid,
+            'type': 'file',
+            'file': f'notes/{names[nid]}.md',
+            'x': cx + (i % cols) * GAP_X,
+            'y': cy + (i // cols) * GAP_Y,
+            'width': NODE_W,
+            'height': NODE_H,
+            'color': PRESET[ci % len(PRESET)],
+        })
+    cx += bw + MARGIN
+    row_h = max(row_h, bh)
+
+for e in links:
+    s, t = e.get('source'), e.get('target')
+    if s in shown_set and t in shown_set:
+        canvas_edges.append({
+            'id': f'e{len(canvas_edges)}',
+            'fromNode': canvas_id[s],
+            'fromSide': 'right',
+            'toNode': canvas_id[t],
+            'toSide': 'left',
+            'toEnd': 'arrow',
+            'label': str(e.get('relation') or ''),
+        })
+
+with open(os.path.join(out, f'{note_name(project)}.canvas'), 'w', encoding='utf-8') as fh:
+    json.dump({'nodes': canvas_nodes, 'edges': canvas_edges}, fh, indent=2)
+
+# ------------------------------------------------------------ vault settings
+conf = os.path.join(out, '.obsidian')
+os.makedirs(conf, exist_ok=True)
+with open(os.path.join(conf, 'app.json'), 'w', encoding='utf-8') as fh:
+    json.dump({'attachmentFolderPath': 'notes', 'newLinkFormat': 'shortest',
+               'useMarkdownLinks': False, 'alwaysUpdateLinks': True}, fh, indent=2)
+with open(os.path.join(conf, 'appearance.json'), 'w', encoding='utf-8') as fh:
+    json.dump({'accentColor': ''}, fh, indent=2)
+with open(os.path.join(conf, 'core-plugins.json'), 'w', encoding='utf-8') as fh:
+    json.dump(['file-explorer', 'global-search', 'switcher', 'graph', 'backlink',
+               'outgoing-link', 'tag-pane', 'page-preview', 'canvas', 'outline'], fh, indent=2)
+
+print(f'  {len(names)} notes, {len(links)} relations, {len(clusters)} clusters')
+print(f'  canvas: {len(canvas_nodes)} nodes, {len(canvas_edges)} edges')
+if len(names) > len(shown):
+    # Never let a cap look like completeness: the notes hold everything, the canvas
+    # holds the most connected slice of it.
+    print(f'  canvas capped at MAX_CANVAS_NODES={max_canvas}: showing the {len(shown)} '
+          f'most connected of {len(names)} entities. Every entity still has a note.')
+PYEOF
+  then
+    echo "";
+    echo "Could not build the vault — the graph above was left untouched.";
+    rm -rf "${tmp}" ;
+    return 1 ;
+  fi
+
+  rm -rf "${vault}" ;
+  mv "${tmp}" "${vault}" ;
+
+  echo "";
+  echo "*---------------------------------------------------------------------*";
+  echo "  Vault ready:";
+  echo "    ${vault}";
+  echo "";
+  echo "  Open it:  obsidian://open?path=$(printf '%s' "${vault}" | sed 's|/|%2F|g')";
+  echo "  or point Obsidian at the folder above (Open folder as vault).";
+  echo "*---------------------------------------------------------------------*";
+}
+
+# Throw the vault away. The graph it was made from is left alone.
+function obsidian_remove() {
+  local ws="${doc_name}" project="${PROJECT_NAME}";
+  local vault; vault=$(obsidian_vault_dir "${ws}" "${project}");
+
+  if [ ! -d "${vault}" ] ; then
+    echo "No Obsidian vault for ${ws}/${project}." ;
+    return 0 ;
+  fi
+  rm -rf "${vault}" ;
+  echo "Removed the Obsidian vault for ${ws}/${project}. The graph is untouched." ;
+}
+
+# What is there, without building anything.
+function obsidian_status() {
+  local ws="${doc_name}" project="${PROJECT_NAME}";
+  local vault; vault=$(obsidian_vault_dir "${ws}" "${project}");
+
+  if [ ! -d "${vault}" ] ; then
+    echo "${ws}/${project}: no vault yet." ;
+    return 0 ;
+  fi
+  echo "${ws}/${project}: $(find "${vault}/notes" -name '*.md' 2>/dev/null | wc -l) notes at ${vault}" ;
+}