@f12r/f12r 1.0.0 → 1.0.1

package/AI_CONTEXT.md

@@ -0,0 +1,186 @@
+# AI Context For f12r
+
+This file is meant to help a future AI agent understand the `f12r` project quickly.
+
+## Project Identity
+
+- Project name: `f12r`
+- CLI command: `f12r`
+- Source repository: `https://github.com/FahimMuntashir/f12r`
+- npm package: `@f12r/f12r`
+- Homebrew tap repository: `https://github.com/FahimMuntashir/homebrew-f12r`
+- Homebrew install command: `brew install FahimMuntashir/f12r/f12r`
+
+## Project Purpose
+
+`f12r` is a macOS-focused Node.js CLI that helps developers set up and manage a development environment.
+
+Main commands:
+
+- `f12r doctor`
+- `f12r setup`
+- `f12r uninstall`
+
+Bonus command behavior:
+
+- `f12r setup --all`
+
+## Tech Stack
+
+- Node.js
+- CommonJS modules
+- `commander`
+- `inquirer`
+- `chalk`
+- `ora`
+- `execa`
+
+## Current Source Structure
+
+- [index.js](/Users/innospace/Desktop/f12r/index.js): CLI entrypoint and command registration
+- [commands/doctor.js](/Users/innospace/Desktop/f12r/commands/doctor.js): doctor command
+- [commands/setup.js](/Users/innospace/Desktop/f12r/commands/setup.js): setup command
+- [commands/uninstall.js](/Users/innospace/Desktop/f12r/commands/uninstall.js): uninstall command
+- [utils/checker.js](/Users/innospace/Desktop/f12r/utils/checker.js): command detection and version checks
+- [utils/installer.js](/Users/innospace/Desktop/f12r/utils/installer.js): Homebrew/npm install helpers and VS Code extension installs
+- [utils/logger.js](/Users/innospace/Desktop/f12r/utils/logger.js): colored log wrappers
+- [utils/prompts.js](/Users/innospace/Desktop/f12r/utils/prompts.js): Inquirer prompt helpers
+- [package.json](/Users/innospace/Desktop/f12r/package.json): package metadata and CLI bin declaration
+
+## Important Functional Behavior
+
+### `doctor`
+
+Checks:
+
+- Homebrew
+- Git
+- Node.js
+- npm
+- Docker
+- VS Code
+
+Shows installed/not installed and version when available.
+
+### `setup`
+
+- ensures Homebrew exists
+- checks installed tools
+- skips tools already installed
+- prompts to install missing tools unless `--all` is used
+- optionally installs VS Code extensions:
+- `esbenp.prettier-vscode`
+- `dbaeumer.vscode-eslint`
+- `GitHub.copilot`
+
+### `uninstall`
+
+- shows supported removable tools
+- uses Homebrew uninstall
+- prompts before uninstalling
+
+## Publishing History And Constraints
+
+### npm naming
+
+The unscoped name `f12r` was rejected by npm because it was too similar to an existing package.
+
+The working package name is:
+
+```json
+"name": "@f12r/f12r"
+```
+
+### CLI command name
+
+Even though the npm package is scoped, the user-facing command remains:
+
+```json
+"bin": {
+  "f12r": "index.js"
+}
+```
+
+### Homebrew
+
+Homebrew installation currently works through a custom tap, not `homebrew/core`.
+
+Supported public install command:
+
+```bash
+brew install FahimMuntashir/f12r/f12r
+```
+
+Not supported yet:
+
+```bash
+brew install f12r
+```
+
+## Homebrew Formula Details
+
+Tap local path on the maintainer machine:
+
+```bash
+/opt/homebrew/Library/Taps/fahimmuntashir/homebrew-f12r
+```
+
+Formula path:
+
+```bash
+/opt/homebrew/Library/Taps/fahimmuntashir/homebrew-f12r/Formula/f12r.rb
+```
+
+Current formula strategy:
+
+- `depends_on "node"`
+- installs from npm tarball URL
+- uses `system "npm", "install", *std_npm_args`
+- wraps the `f12r` executable with `write_env_script`
+
+## Important Operational Notes
+
+### If a maintainer wants to release a new version
+
+Use [RELEASE_GUIDE.md](/Users/innospace/Desktop/f12r/RELEASE_GUIDE.md).
+
+High-level flow:
+
+1. change code
+2. bump version
+3. push git changes and tags
+4. publish npm package
+5. update Homebrew formula URL and SHA
+6. test brew install
+7. push the tap repo
+
+### If `brew untap` breaks the shell
+
+This happened before because the shell was inside the tap directory when untapping it.
+
+Always move elsewhere first:
+
+```bash
+cd ~
+brew untap FahimMuntashir/f12r
+```
+
+### If npm tokens are exposed
+
+Revoke them immediately from npm account settings.
+
+## Recommended Future Improvements
+
+- add automated tests
+- add a proper README with examples and screenshots or terminal demos
+- add GitHub Actions for lint/test on the source repo
+- optionally support more tools
+- optionally detect missing VS Code `code` shell command more explicitly
+
+## Best Files To Read First For Any Future Agent
+
+1. [package.json](/Users/innospace/Desktop/f12r/package.json)
+2. [index.js](/Users/innospace/Desktop/f12r/index.js)
+3. [utils/checker.js](/Users/innospace/Desktop/f12r/utils/checker.js)
+4. [utils/installer.js](/Users/innospace/Desktop/f12r/utils/installer.js)
+5. [RELEASE_GUIDE.md](/Users/innospace/Desktop/f12r/RELEASE_GUIDE.md)

package/README.md

@@ -0,0 +1,113 @@
+# f12r
+
+`f12r` is a macOS CLI for checking, installing, and uninstalling common developer tools.
+
+It helps developers:
+
+- inspect their machine with `f12r doctor`
+- install missing tools with `f12r setup`
+- install everything non-interactively with `f12r setup --all`
+- remove supported tools with `f12r uninstall`
+
+## Features
+
+- checks for Homebrew, Git, Node.js, npm, Docker, and VS Code
+- shows friendly colored output
+- installs missing tools with Homebrew
+- installs selected VS Code extensions
+- supports interactive and `--all` setup flows
+- works as a global CLI command: `f12r`
+
+## Install
+
+### Homebrew
+
+```bash
+brew install FahimMuntashir/f12r/f12r
+```
+
+### npm
+
+```bash
+npm install -g @f12r/f12r
+```
+
+## Quick Start
+
+```bash
+f12r --help
+f12r doctor
+f12r setup
+```
+
+## Commands
+
+### `f12r doctor`
+
+Checks whether these tools are installed:
+
+- Homebrew
+- Git
+- Node.js
+- npm
+- Docker
+- VS Code
+
+It also shows version info when available.
+
+### `f12r setup`
+
+- detects missing tools
+- installs Homebrew automatically if needed
+- asks before installing each missing tool
+- can install these VS Code extensions:
+- `esbenp.prettier-vscode`
+- `dbaeumer.vscode-eslint`
+- `GitHub.copilot`
+
+### `f12r setup --all`
+
+Installs all missing supported tools without per-tool prompts.
+
+### `f12r uninstall`
+
+Lets the user choose a supported tool to remove with Homebrew.
+
+## Local Development
+
+```bash
+npm install
+node index.js --help
+node index.js doctor
+node index.js setup
+node index.js uninstall
+```
+
+To link it globally on your machine:
+
+```bash
+npm link
+```
+
+## Tech Stack
+
+- Node.js
+- CommonJS
+- commander
+- inquirer
+- chalk
+- ora
+- execa
+
+## Project Links
+
+- GitHub source: `https://github.com/FahimMuntashir/f12r`
+- Homebrew tap: `https://github.com/FahimMuntashir/homebrew-f12r`
+- npm package: `@f12r/f12r`
+
+## Maintainer Notes
+
+If you are updating or republishing this project later, use:
+
+- `RELEASE_GUIDE.md` for the full release workflow
+- `AI_CONTEXT.md` for future AI-agent handoff context

package/RELEASE_GUIDE.md

@@ -0,0 +1,289 @@
+# f12r Release Guide
+
+This file is a beginner-friendly guide for publishing and updating `f12r`.
+
+## Quick Summary
+
+The project has 3 public pieces:
+
+1. Source code repository
+2. npm package
+3. Homebrew formula
+
+Current public setup:
+
+- GitHub source repo: `https://github.com/FahimMuntashir/f12r`
+- Homebrew tap repo: `https://github.com/FahimMuntashir/homebrew-f12r`
+- npm package name: `@f12r/f12r`
+- Homebrew install command: `brew install FahimMuntashir/f12r/f12r`
+
+## One-Time Setup That Is Already Done
+
+These are already completed for this project:
+
+- GitHub repo created
+- npm account connected
+- npm package published
+- Homebrew tap created
+- Homebrew formula added
+- Global `brew install FahimMuntashir/f12r/f12r` tested successfully
+
+## How Users Install f12r
+
+### Option 1: Homebrew
+
+```bash
+brew install FahimMuntashir/f12r/f12r
+```
+
+### Option 2: npm
+
+```bash
+npm install -g @f12r/f12r
+```
+
+## Very Important Safety Notes
+
+### 1. If you ever paste an npm token somewhere public
+
+Revoke it immediately in npm account settings and create a new token.
+
+### 2. Do not rename the CLI command
+
+The npm package name is scoped as `@f12r/f12r`, but the actual command should stay:
+
+```bash
+f12r
+```
+
+### 3. `brew install f12r` is not available yet
+
+The public install command for now is:
+
+```bash
+brew install FahimMuntashir/f12r/f12r
+```
+
+`brew install f12r` only becomes possible if Homebrew later accepts the package into `homebrew/core`.
+
+## Normal Release Flow For A New Version
+
+Example: releasing `1.0.1`
+
+### Step 1. Make your code changes
+
+Update the source code in this repo and test locally:
+
+```bash
+npm install
+node index.js doctor
+node index.js --help
+```
+
+If needed:
+
+```bash
+node index.js setup
+node index.js uninstall
+```
+
+### Step 2. Bump the version
+
+For a patch release:
+
+```bash
+npm version patch
+```
+
+For a minor release:
+
+```bash
+npm version minor
+```
+
+For a major release:
+
+```bash
+npm version major
+```
+
+This updates `package.json`, updates `package-lock.json`, and creates a git tag.
+
+### Step 3. Push source code to GitHub
+
+```bash
+git push
+git push --tags
+```
+
+### Step 4. Publish the new npm version
+
+```bash
+npm publish --access=public
+```
+
+Then verify:
+
+```bash
+npm view @f12r/f12r version
+```
+
+If npm has a short delay, wait a few minutes and try again.
+
+### Step 5. Update the Homebrew formula
+
+The formula lives in the tap repo, not in this source repo.
+
+Formula path:
+
+```bash
+/opt/homebrew/Library/Taps/fahimmuntashir/homebrew-f12r/Formula/f12r.rb
+```
+
+Update:
+
+- `url`
+- `sha256`
+
+The URL format will be:
+
+```bash
+https://registry.npmjs.org/@f12r/f12r/-/f12r-VERSION.tgz
+```
+
+Example:
+
+```bash
+https://registry.npmjs.org/@f12r/f12r/-/f12r-1.0.1.tgz
+```
+
+### Step 6. Get the new SHA256
+
+Run:
+
+```bash
+curl -L https://registry.npmjs.org/@f12r/f12r/-/f12r-1.0.1.tgz | shasum -a 256
+```
+
+Copy the SHA256 output into the formula.
+
+### Step 7. Test the Homebrew formula
+
+First move to a safe existing directory:
+
+```bash
+cd ~
+```
+
+Then run:
+
+```bash
+brew audit --strict FahimMuntashir/f12r/f12r
+brew reinstall --build-from-source FahimMuntashir/f12r/f12r
+f12r --version
+f12r doctor
+```
+
+If `brew reinstall` gives trouble, use:
+
+```bash
+brew uninstall f12r
+brew install FahimMuntashir/f12r/f12r
+```
+
+### Step 8. Push the updated formula
+
+```bash
+cd /opt/homebrew/Library/Taps/fahimmuntashir/homebrew-f12r
+git status
+git add Formula/f12r.rb
+git commit -m "Update f12r to 1.0.1"
+git push
+```
+
+After this, Homebrew users can install the new version.
+
+## First-Time Homebrew Formula Reference
+
+Current working formula:
+
+```rb
+class F12r < Formula
+  desc "CLI to set up and manage a macOS development environment"
+  homepage "https://github.com/FahimMuntashir/f12r"
+  url "https://registry.npmjs.org/@f12r/f12r/-/f12r-1.0.0.tgz"
+  sha256 "aa8232c019f1d368f775f973bd743494f7747de6a6db074d6cbe5762a0e660b9"
+  license "MIT"
+
+  depends_on "node"
+
+  def install
+    system "npm", "install", *std_npm_args
+    (bin/"f12r").write_env_script libexec/"bin/f12r", PATH: "#{Formula["node"].opt_bin}:$PATH"
+  end
+
+  test do
+    assert_match "f12r", shell_output("#{bin}/f12r --help")
+  end
+end
+```
+
+## Common Problems
+
+### Problem: npm says package name is too similar to another package
+
+Use the scoped npm package name:
+
+```json
+"name": "@f12r/f12r"
+```
+
+### Problem: `npm view @f12r/f12r version` returns 404 right after publish
+
+Wait a few minutes and try again. npm can take a short time to update.
+
+### Problem: `brew untap` breaks the current terminal directory
+
+This happens if you are standing inside the tap folder while untapping it.
+
+Wrong:
+
+```bash
+cd /opt/homebrew/Library/Taps/fahimmuntashir/homebrew-f12r
+brew untap FahimMuntashir/f12r
+```
+
+Correct:
+
+```bash
+cd ~
+brew untap FahimMuntashir/f12r
+```
+
+### Problem: Homebrew install works locally but not for others
+
+Check these:
+
+- the tap repo was pushed to GitHub
+- the formula file was committed and pushed
+- the npm tarball URL in the formula is correct
+- the SHA256 matches the published tarball
+
+### Problem: `brew install f12r` does not work
+
+That is expected for now.
+
+Use:
+
+```bash
+brew install FahimMuntashir/f12r/f12r
+```
+
+## What To Tell Future AI Agents
+
+If you use another AI later, share:
+
+- [AI_CONTEXT.md](/Users/innospace/Desktop/f12r/AI_CONTEXT.md)
+- [RELEASE_GUIDE.md](/Users/innospace/Desktop/f12r/RELEASE_GUIDE.md)
+
+That will give the AI the correct project and publishing context quickly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f12r/f12r",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A macOS developer environment setup and management CLI.",
   "main": "index.js",
   "bin": {