feat: Add appstash package for simple application directory resolution

[pyramation]

feat: Add appstash package for application directory resolution

Summary

Created a new appstash package that provides simple, clean application directory resolution for Node.js CLI tools. This is a relocation of @launchql/appdirs from the launchql/launchql monorepo, adapted to fit the hyperweb-io/dev-utils conventions.

Key Features:

• Simple API: appstash(tool, options) returns all app directories
• Clean structure: ~/.<tool>/{config,cache,data,logs} + /tmp/<tool>
• Graceful fallback chain: home directory → XDG directories → system temp
• No throws: Always returns valid paths, never throws errors
• Zero dependencies: Pure Node.js implementation
• Full TypeScript support

API Surface:

• appstash(tool, options?) - Get all directories for a tool
• ensure(dirs) - Create directories if they don't exist
• resolve(dirs, kind, ...parts) - Resolve paths within directories

Testing:

• 17 unit tests passing
• Build successful
• Follows existing package conventions (tsconfig, jest, build scripts)

Review & Testing Checklist for Human

⚠️ Risk Level: YELLOW - New package with untested fallback logic and naming considerations

• Verify package naming convention - This package uses unscoped name appstash while all other packages in this repo use @interweb/ scope. Confirm this is intentional. If it should be scoped, update package.json name field to @interweb/appstash.
• Test actual fallback behavior - The unit tests use baseDir option to avoid mocking, so the real XDG/tmp fallback paths aren't fully tested. Manually test by simulating home directory failure (e.g., chmod 000 ~/.test-tool) to verify fallback works correctly.
• Verify npm package availability - If publishing is intended, check that the package name "appstash" is available on npm (or update to scoped name if needed).

Test Plan

# 1. Install and build
cd packages/appstash
pnpm install
pnpm build
pnpm test

# 2. Basic functionality test
node -e "
const { appstash, ensure } = require('./dist/index.js');
const dirs = appstash('test-tool', { ensure: true });
console.log('Directories created:', dirs);
console.log('Used fallback?', dirs.usedFallback);
"

# 3. Test fallback behavior (simulate home directory failure)
mkdir -p /tmp/readonly-test
chmod 444 /tmp/readonly-test
node -e "
const { appstash } = require('./dist/index.js');
const dirs = appstash('test', { baseDir: '/tmp/readonly-test', ensure: true });
console.log('Fallback used?', dirs.usedFallback);
console.log('Directories:', dirs);
"

Notes

• This is a relocation from @launchql/appdirs in the launchql/launchql repo
• All 17 tests passing locally
• Build successful with both CommonJS and ESM outputs
• Comprehensive documentation included (README.md + USAGE_SCENARIOS.md)
• Follows existing package structure and conventions in this repo

Session Info:

• Devin session: https://app.devin.ai/sessions/4d7a6824a623483081ec933fbe77abfe
• Requested by: Dan Lynch ([email protected]) / @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring