@hasna/files weekly downloads statistics

@hasna/files

Agent-first file management — index local folders and S3 buckets, sync Google Drive, tag, search, and retrieve files via CLI + MCP

Install

The published executables use Bun. The client talks to the hosted files service through the ONE @hasna/contracts credential resolver, resolved fresh on every request: the macOS Keychain item hasna.credentials.files.api-key (account HASNA_STATION, else the short hostname, else $USER), the disk credential file ~/.hasna/files/config/credentials (owner-only 0400/0600), or HASNA_FILES_API_KEY. The service authority follows the same ladder — HASNA_FILES_API_URL, the Keychain api-url item, the credentials file — and defaults to the fleet gateway https://api.hasna.com/files once a credential resolves, so a key alone is a complete configuration. The unprefixed FILES_API_URL / FILES_API_KEY names survive only as a silent alias inside the resolver for one release; the canonical HASNA_FILES_* names work and win.

Without any resolvable credential the CLI fails closed — non-zero exit, no SQLite, no *-local-fallback event. Local SQLite mode is an explicit opt-in: set HASNA_FILES_LOCAL=1 (alias FILES_LOCAL=1), and no credential or PostgreSQL/S3 configuration is required for local folders. Every local run prints one files: LOCAL mode — ... line on stderr so an unhosted run is never mistaken for an empty hosted one. The retired HASNA_FILES_LOCAL_MODE / FILES_LOCAL_MODE / *_STORAGE_MODE switches are gone, and nothing reads ~/.hasna/fleet-env, ~/.hasna/cloud, ~/.config/hasna or $XDG_CONFIG_HOME.

Documentation

• CLI reference • MCP server and tool catalog • HTTP service, client modes, migrations, and SDK • Evidence storage contract • Knowledge source contract

CLI Usage

The CLI supports local SQLite mode (explicit opt-in: HASNA_FILES_LOCAL=1 / FILES_LOCAL=1) and a hosted HTTP API mode. With neither a resolvable credential nor the local opt-in set, commands fail closed with an error naming every credential tier the resolver consulted — never a silent local session. Commands that need on-box bytes or ingestion state fail explicitly in API mode; the complete command and availability matrix is in the CLI reference.

Build bounded agent context packs with citations instead of dumping full files:

Context packs print compact deterministic JSON with attachment_refs, citations, bounded excerpts, and omitted counts. Secret-like values are redacted by default; repeat --redact for local policy patterns. Use --out to write the bounded pack as a local artifact and print a compact pointer.

Google Drive Sync

Google Drive sync uses profiles configured through the connectors CLI:

Add or repair your S3 destination once. This stores the AWS named profile on the source and sets it as the default Google Drive destination. This package ships no default bucket or AWS profile — set HASNA_FILES_S3_BUCKET (and optionally HASNA_FILES_AWS_PROFILE) or pass --bucket/--aws-profile explicitly:

bootstrap-prod-files (aliased bootstrap-prod-emails) creates or updates a single canonical S3 source rooted at s3:///imports/google-drive/live and sets it as the default Google Drive destination; new imports land below that root under /.... The --aws-profile flag defaults to the standard AWS SDK default profile (or HASNA_FILES_AWS_PROFILE if set) — never a hardcoded profile name. Operator-specific bucket names, legacy bucket aliases, and migration runbooks are internal evidence and are not shipped in the public package.

For a custom S3 destination, pass the shared AWS profile explicitly:

To sync into local storage instead, add a local source and pass it as the destination:

Google Drive rows retain their Drive source identity while the resolver follows the configured S3 or local destination for bytes. Use files resolve or files download for those stored copies. files where is limited to files whose source itself is local.

To organize the migrated Google Drive corpus into the unified files taxonomy, run the policy command as a dry-run first:

This updates review metadata only: owner, normalized virtual target path, duplicate status, and broad additive permission metadata. Canonical S3 objects stay under objects/sha256/, and legacy/import buckets stay readable until the final retirement audit.

MCP Server

files-mcp defaults to the token-bounded standard profile. Select HASNA_FILES_MCP_PROFILE=minimal|standard|full before startup (legacy alias: OPEN_FILES_MCP_PROFILE). minimal exposes discovery and metadata reads, standard adds bounded content and audit reads (plus local context-pack tools when the server is in explicit local mode), and full preserves the complete legacy inventory.

Reduced profiles register capability-gated tools only when their required mutation, destructive, import, signed URL, download, or indexing capabilities are enabled:

list_files and search_files default to compact, minified 20-row pages with count, limit, offset, next_offset, query-bound cursor/next_cursor, has_more, end_reached, and whole-query complete; compact pages additionally report the enforced byte budget. Set format: "legacy" for the historical full bare array. CLI list/search --json uses the same compact default and --json --full is the legacy compatibility escape (--agent-json remains a deprecated compact alias). Pages are capped at 500 rows; use detail: "full" for full page records or fields for an exact compact projection (id is always retained). all: true exhausts from offset zero within a 5,000-row/1-MiB hard safety boundary and refuses rather than claiming partial success. get_file remains the exact full-detail path.

The standard profile exposes read-only build_context_pack and search_context_pack for bounded excerpts, citations, attachment refs, and omitted counts in local mode. Hosted calls keep a tested refusal: there is no owned bounded-pack /v1 route yet, so the client never downloads an unbounded corpus or falls back to local SQLite.…

Description from the npm listing.