Plocate

@kneel/plocatev2026.07.15.2· 11d agoMODELS

01README

Wrap plocate to build, refresh, query, and expire a fast filesystem index — so extensions and agents resolve paths without walking directory trees. This model owns the index lifecycle and cache-freshness policy: staleness is native swamp TTL (the index resource's lifetime = maxAge), so an expired index simply stops resolving until rebuilt. Transport defaults to local, with toolbox/podman/commandPrefix escape hatches and an Ansible-style become to stack sudo for system builds.

Methods

build / refresh — rebuild every root's DB in one execution; write the aggregate index instance main (lifetime = maxAge).
refresh_all — fan-out: rebuild every root in ONE execution / one lock; write one index per root (slugged path name) plus aggregate main.
status — stat DB mtimes host-side, compute stale vs maxAge; no rebuild.
clear — delete the user DB(s) (verified inside dbDir) and mark the index cleared. Never touches the system DB.
query — match against the index and persist a CEL-referenceable results instance (q-<label>). refreshIfStale self-heals a stale index first; scope: "system" queries the read-only system DB.

Quickstart

swamp model create @kneel/plocate rpm-index \
  --global-arg roots='["/home/neil/dev/fedora/rpms/swamp"]'
swamp model method run rpm-index build
swamp model method run rpm-index query --arg pattern='.spec' --arg label=specs

Consume the results with CEL (prefer data.latest(...); its 2nd arg is the instance name — main for the index, q-<label> for a query):

data.latest("rpm-index", "q-specs").attributes.matches

Selected examples

Fan-out over matches — index a corpus once, then let another model iterate the matches instead of walking directories:

# consuming model's forEach source:
data.latest("rpm-index", "q-specs").attributes.matches

Pre-flight existence gate — a deploy check confirms a built asset exists before acting, no filesystem crawl in the hot path:

swamp model method run artifacts query \
  --arg pattern='app-v2.3.1.tar.gz' --arg limit=1 \
  --arg refreshIfStale=true --arg label=asset

# gate the deploy step on a nonzero match count:
data.latest("artifacts", "q-asset").attributes.count > 0

Agent "where is X" — instant path resolution by name or regex, self-healing if the index went stale:

swamp model method run home-index query \
  --arg pattern='plocate.*\.ts$' --arg regex=true \
  --arg refreshIfStale=true --arg label=find-plocate

Full docs — deployment requirements, transport + become, the global-argument reference, and the complete 12-example catalog (nightly refresh_all cron, multi-root queries, cross-model CEL wiring, backup verification): https://github.com/NeilHanlon/swamp-plocate

02Models1

@kneel/plocatev2026.07.15.2plocate.ts

Global Arguments

Argument	Type	Required	Description
roots	array	yes	Directories to index. One plocate DB is built per root; roots are queryable together (db1:db2).
dbDir	string	yes	Directory holding user-owned plocate DBs. '~' is expanded to $HOME.
maxAge	string	yes	Freshness threshold. Drives the `index` resource lifetime (native staleness) and refreshIfStale self-heal.
requireVisibility	union	yes	plocate updatedb --require-visibility. 0 = report all files without a visibility check (user corpus DBs).
prunePaths	array	yes	Paths to omit from the index (updatedb --prunepaths).
pruneNames	array	yes	Directory names to omit from the index (updatedb --prunenames).
runtime	enum	yes	Transport for running plocate/updatedb. 'local' runs on PATH; toolbox/podman hop into a container.
container	string	yes	Container name — required when runtime is 'toolbox' or 'podman'.
commandPrefix	array	yes	Escape hatch: verbatim transport prefix (e.g. ['ssh','host'] or ['nsenter',...]). Overrides `runtime` when non-empty.
become	boolean	yes	Ansible-style privilege escalation: prepend 'sudo' after the transport prefix. Per-method `become` overrides this.
systemDb	string	yes	Path to a system-wide plocate DB, for read-only queries with scope:'system'.
plocateBin	string	yes	plocate binary name/path on the transport target.
updatedbBin	string	yes	plocate's updatedb binary name/path on the transport target.
metadata	record	yes

fn build(become?: boolean)

Build (or rebuild) the plocate DB for every configured root in one execution, then write the aggregate `index` resource (lifetime == maxAge).

Argument	Type	Required	Description
become?	boolean	no	Override the global `become` for this build (sudo on the transport target).

fn refresh(become?: boolean)

Alias for `build`: rebuild every configured root and rewrite the aggregate `index`.

Argument	Type	Required	Description
become?	boolean	no	Override the global `become` for this refresh.

fn refresh_all(become?: boolean)

Fan-out rebuild (Rule 6): rebuild every configured root in ONE execution / one lock, writing one `index` instance PER root (dynamic names) plus the aggregate `main`, for granular CEL referencing.

Argument	Type	Required	Description
become?	boolean	no	Override the global `become` for this rebuild.

fn status()

Report index freshness without rebuilding: reads DB mtime(s) host-side and compares against maxAge. Use `status.stale` to gate workflows.

fn clear()

Verify each DB path (Rule 5) then delete the user DB file(s) and overwrite `index` with a cleared marker (stale:true, fileCount:0). Does NOT touch the system DB.

fn query(pattern: string, limit?: number, regex: boolean, ignoreCase: boolean, refreshIfStale: boolean, scope: enum, label?: string)

Query the index for a pattern; persist matches as a `results` resource and return them. Self-heals (rebuilds) first when refreshIfStale and the DB is older than maxAge. scope:'system' queries the read-only systemDb.

Argument	Type	Required	Description
pattern	string	yes	Search pattern (glob-ish substring by default; regexp when regex:true).
limit?	number	no	Stop after N matches (plocate -l).
regex	boolean	yes	Interpret pattern as a basic regexp (plocate --regexp).
ignoreCase	boolean	yes	Case-insensitive match (plocate -i).
refreshIfStale	boolean	yes	If the user index is older than maxAge, rebuild it before querying (self-heal). Ignored for scope:'system'.
scope	enum	yes	'user' queries the per-root corpus DBs; 'system' queries the read-only systemDb.
label?	string	no	Stable name for the persisted results instance, referenced as data.latest("<model>", "q-<label>"). Defaults to a deterministic hash of the query args.

Resources

index(24h)— Metadata for a built plocate index. Lifetime == maxAge, so expiry IS the staleness signal.

results(1h)— Persisted matches from a query, referenceable via CEL.

03Previous Versions1

2026.07.15.1Jul 15, 2026

04Stats

100 / 100

Downloads

Archive size

21.2 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/NeilHanlon/swamp-plocate

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#plocate #locate #filesystem #index #search