@hugomrdias/fil 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@hugomrdias/fil",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Command-line interface for Filecoin storage",
+  "license": "MIT",
+  "author": "Hugo Dias <hugomrdias@gmail.com>",
+  "homepage": "https://github.com/hugomrdias/fil/tree/main/packages/fil-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hugomrdias/fil.git",
+    "directory": "packages/fil-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hugomrdias/fil/issues"
+  },
+  "type": "module",
+  "bin": {
+    "fil": "./bin/fil.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@filoz/synapse-core": "^0.10.0",
+    "@ipld/car": "^5.4.7",
+    "@types/node": "26.5.1",
+    "clipact": "0.0.0",
+    "env-paths": "^4.0.0",
+    "esbuild": "0.28.2",
+    "ipfs-unixfs-exporter": "^16.2.3",
+    "ipfs-unixfs-importer": "^16.1.5",
+    "iso-conf": "^0.4.2",
+    "multiformats": "^14.0.5",
+    "typescript": "7.0.2",
+    "viem": "^2.56.9",
+    "zod": "4.6.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist skills",
+    "build": "node scripts/build.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test 'test/**/*.test.ts'",
+    "lint": "biome check .",
+    "check": "pnpm typecheck && pnpm test && pnpm lint"
+  }
 }

package/skills/fil/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: fil
+description: Store files and folders on Filecoin with the fil CLI and return retrieval links; download, list, delete, and resume interrupted uploads. Use when the user asks to publish, store, share, or retrieve content on Filecoin or FOC.
+---
+
+# fil
+
+`fil` stores a file (exact bytes) or a folder (a UnixFS CAR served over IPFS) on Filecoin and returns a link. Every command writes one JSON object to stdout when run by an agent; it has `data` on success or `error` on failure. Branch on `error.code`, never on stderr text.
+
+## Discover before you call
+
+- `fil schema --list` lists every command with its side effects.
+- `fil schema <command>` gives the input JSON Schema, the JSON Schema of `data`, and what each error code means, for the installed version. Prefer it over guessing flags.
+
+## Workflow
+
+1. `fil status` shows whether a session key is active and the account is funded.
+2. `fil put <path> --dry-run` shows the size, provider, cost, and any missing authorization without storing anything.
+3. `fil put <path>` (or `fil publish <path>`) stores it. Return `data.urls.browser` to the user exactly as given, with `data.resource.ref`. `data.urls.piece` serves the exact stored bytes. A new link can return 404 until the indexer behind it has the piece; `fil inspect <ref> --check` reports when it answers.
+4. `fil get <ref>` downloads and verifies content; `fil ls` and `fil inspect <ref>` find what was stored.
+
+## Rules
+
+- Never ask for or pass a private key. Logging in needs the user: `auth_required` or `login_pending` means relay the `by: "user"` step (the fil-app approval link) and stop. After the user approves, run `fil login` once to confirm.
+- `insufficient_funds` and `session_expired` also need the user; relay their `next` steps.
+- `fil delete <ref>` needs `--yes`. On `confirmation_required`, relay the reason and rerun with `--yes` only after the user agrees.
+- Never repeat a failed or interrupted `put` or `delete`: that starts a new paid operation. Run the `fil operations resume <id>` command from `next` instead; errors with a fil code also carry the ID in `error.details.operationId`. Find lost operation IDs with `fil operations ls --incomplete`.
+- Retry only when `error.retryable` is `true`, after `retryAfterSeconds` when present.