@kansei-link/bantou 0.2.0

package/dist/classifier/two-stage-classifier.js

@@ -0,0 +1,51 @@
+// Two-stage classifier orchestrator.
+//
+// Stage 1: keyword dict (= fast, deterministic, free)
+// Stage 2: Claude API fallback (= slow-ish, AI, paid)
+//
+// If Stage 1 matches → return immediately (= ~95% of typical transactions).
+// If no match → try Stage 2 (= remaining ~5%). If both miss → return
+// unclassified (= human review queue).
+export class TwoStageClassifier {
+    stage1;
+    stage2;
+    constructor(stage1, stage2) {
+        this.stage1 = stage1;
+        this.stage2 = stage2 || null;
+    }
+    async classify(tx) {
+        // Stage 1: keyword match
+        const s1 = this.stage1.classify(tx);
+        if (s1.classified) {
+            return { ...s1, stage: 1 };
+        }
+        // Stage 2: Claude API fallback (= only if configured)
+        if (this.stage2) {
+            const s2 = await this.stage2.classify(tx);
+            if (s2.classified) {
+                return { ...s2, stage: 2 };
+            }
+            // Stage 2 also failed → return its failure reason
+            return { ...s2, stage: 'unclassified' };
+        }
+        // No Stage 2 configured → return Stage 1 result (unclassified)
+        return { ...s1, stage: 'unclassified' };
+    }
+    hasStage2() {
+        return this.stage2 !== null;
+    }
+    getStage1() {
+        return this.stage1;
+    }
+    getStage2() {
+        return this.stage2;
+    }
+}
+/**
+ * Helper: extract category metadata from keyword dict for ClaudeClassifier construction.
+ * Reads from KeywordClassifier's internal data via a getCategories() method.
+ */
+export function extractCategoryMeta(classifier) {
+    return classifier.getCategoriesMeta();
+}
+//# sourceMappingURL=two-stage-classifier.js.map

package/dist/classifier/types.d.ts

@@ -0,0 +1,31 @@
+export interface Transaction {
+    amount: number;
+    memo: string;
+    date: string;
+    partner_name?: string;
+    company_id?: number;
+}
+export interface ClassificationResult {
+    classified: boolean;
+    category_id?: string;
+    category_name_ja?: string;
+    freee_account_code?: number;
+    tax_code?: number;
+    confidence: 'high' | 'medium' | 'low' | 'none';
+    matched_keyword?: string;
+    match_reason: string;
+    classifier_version: string;
+    amount_override_redirect?: string;
+    special_pattern?: string;
+}
+export interface ExclusionResult {
+    excluded: boolean;
+    rule_id?: string;
+    rule_name_ja?: string;
+    reason?: string;
+    suggested_next_step?: string;
+    action_type?: 'human_review' | 'alternative_workflow' | 'skip_silently';
+    alternative_workflow_id?: string;
+    matched_keyword?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/classifier/types.js

@@ -0,0 +1,3 @@
+// Shared types for keyword classifier + exclusion checker.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/connectors/freee.d.ts

@@ -0,0 +1,115 @@
+import { FreeeSecrets } from '../secrets.js';
+export interface FreeeCompany {
+    id: number;
+    display_name: string;
+    tax_at_source_calc_type: number;
+    contact_name: string;
+    fiscal_yearmonth?: string;
+    tax_method?: number;
+    accounting_period_start?: string;
+}
+export interface FreeeDeal {
+    id: number;
+    company_id: number;
+    issue_date: string;
+    type: 'income' | 'expense';
+    partner_id: number | null;
+    partner_name?: string;
+    account_item_id?: number;
+    tax_code?: number;
+    ref_number?: string;
+    amount: number;
+    due_amount: number;
+    status: 'unsettled' | 'settled';
+    details: FreeeDealDetail[];
+    description?: string;
+    memo?: string;
+}
+export interface FreeeDealDetail {
+    id: number;
+    account_item_id: number;
+    tax_code: number;
+    amount: number;
+    description?: string;
+}
+export interface FreeePartner {
+    id: number;
+    name: string;
+    shortcut1?: string;
+    shortcut2?: string;
+}
+export interface FreeeAccountItem {
+    id: number;
+    name: string;
+    shortcut?: string;
+    account_category?: string;
+    account_category_id?: number;
+    tax_code?: number;
+    group_name?: string;
+    available?: boolean;
+}
+export interface CreateDealInput {
+    issue_date: string;
+    type: 'income' | 'expense';
+    amount: number;
+    account_item_id: number;
+    tax_code?: number;
+    partner_id?: number;
+    ref_number?: string;
+    description?: string;
+}
+export declare class FreeeConnector {
+    private secrets;
+    constructor(secrets: FreeeSecrets, opts?: {
+        skipExpiryCheck?: boolean;
+    });
+    private request;
+    /**
+     * List all companies accessible by the current OAuth token.
+     * Multi-company method: a single token grants access to 60+ companies.
+     * freee API: GET /api/1/companies
+     */
+    listCompanies(): Promise<FreeeCompany[]>;
+    getCompany(companyId?: number): Promise<FreeeCompany>;
+    /**
+     * List deals (取引) with optional filters.
+     *
+     * @param opts.company_id  Override company (default: from secrets). Required for multi-company batch.
+     * @param opts.status      Filter by 'unsettled' (未処理) or 'settled' (処理済み).
+     *                         Multi-company method: always fetch 'unsettled' to avoid reprocessing.
+     */
+    listDeals(opts?: {
+        company_id?: number;
+        type?: 'income' | 'expense';
+        status?: 'unsettled' | 'settled';
+        start_issue_date?: string;
+        end_issue_date?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<FreeeDeal[]>;
+    /**
+     * List partners (取引先) for a company.
+     * @param opts.company_id  Override company (default: from secrets).
+     */
+    listPartners(opts?: {
+        company_id?: number;
+        limit?: number;
+        offset?: number;
+    }): Promise<FreeePartner[]>;
+    listAccountItems(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<FreeeAccountItem[]>;
+    createPartner(name: string): Promise<FreeePartner>;
+    createDeal(input: CreateDealInput): Promise<FreeeDeal>;
+    getWalletTxns(opts?: {
+        walletable_type?: 'bank_account' | 'credit_card' | 'wallet';
+        start_date?: string;
+        end_date?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    get companyId(): number;
+    get companyName(): string;
+}
+//# sourceMappingURL=freee.d.ts.map

package/dist/connectors/freee.js

@@ -0,0 +1,177 @@
+// freee API connector for Cockpit MCP.
+//
+// Wraps the freee Accounting API. Auth via Bearer token from secrets.ts.
+// All API calls return parsed JSON or throw with sanitized error messages
+// (= NEVER includes the access token).
+import https from 'node:https';
+import { isTokenExpired } from '../secrets.js';
+const FREEE_API_BASE = 'api.freee.co.jp';
+const FREEE_API_VERSION = '2020-06-15';
+export class FreeeConnector {
+    secrets;
+    constructor(secrets, opts = {}) {
+        this.secrets = secrets;
+        if (!opts.skipExpiryCheck && isTokenExpired(secrets)) {
+            throw new Error('freee access token has expired or is about to expire. ' +
+                'Please refresh manually until OAuth refresh flow is implemented. ' +
+                'Re-issue token at https://developer.freee.co.jp/ and update FREEE_ACCESS_TOKEN ' +
+                '(or ~/.claude/secrets/freee-cockpit-dev.json).');
+        }
+    }
+    request(method, path, body) {
+        const options = {
+            hostname: FREEE_API_BASE,
+            port: 443,
+            path,
+            method,
+            headers: {
+                'Authorization': `Bearer ${this.secrets.access_token}`,
+                'Accept': 'application/json',
+                'X-Api-Version': FREEE_API_VERSION,
+                ...(body ? { 'Content-Type': 'application/json' } : {}),
+            },
+            timeout: 30000,
+        };
+        return new Promise((resolve, reject) => {
+            const req = https.request(options, (res) => {
+                let chunks = '';
+                res.on('data', (chunk) => { chunks += chunk; });
+                res.on('end', () => {
+                    try {
+                        const data = chunks ? JSON.parse(chunks) : {};
+                        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                            resolve(data);
+                        }
+                        else {
+                            // Sanitize error: never echo body if it might contain sensitive data
+                            const errMessage = data.errors
+                                ? JSON.stringify(data.errors).slice(0, 300)
+                                : `HTTP ${res.statusCode}`;
+                            const hint = res.statusCode === 401
+                                ? ' [401 — access token likely expired/invalid; re-issue at https://developer.freee.co.jp/ and update FREEE_ACCESS_TOKEN]'
+                                : '';
+                            reject(new Error(`freee API ${method} ${path} failed: ${errMessage}${hint}`));
+                        }
+                    }
+                    catch (e) {
+                        reject(new Error(`freee API parse error: ${e.message}`));
+                    }
+                });
+            });
+            req.on('error', (e) => reject(new Error(`freee API request error: ${e.message}`)));
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error('freee API timeout (30s)'));
+            });
+            if (body)
+                req.write(JSON.stringify(body));
+            req.end();
+        });
+    }
+    /**
+     * List all companies accessible by the current OAuth token.
+     * Multi-company method: a single token grants access to 60+ companies.
+     * freee API: GET /api/1/companies
+     */
+    async listCompanies() {
+        const data = await this.request('GET', '/api/1/companies');
+        return data.companies;
+    }
+    async getCompany(companyId) {
+        const id = companyId ?? this.secrets.company_id;
+        const data = await this.request('GET', `/api/1/companies/${id}`);
+        return data.company;
+    }
+    /**
+     * List deals (取引) with optional filters.
+     *
+     * @param opts.company_id  Override company (default: from secrets). Required for multi-company batch.
+     * @param opts.status      Filter by 'unsettled' (未処理) or 'settled' (処理済み).
+     *                         Multi-company method: always fetch 'unsettled' to avoid reprocessing.
+     */
+    async listDeals(opts = {}) {
+        const params = new URLSearchParams({
+            company_id: String(opts.company_id ?? this.secrets.company_id),
+            ...(opts.type ? { type: opts.type } : {}),
+            ...(opts.status ? { status: opts.status } : {}),
+            ...(opts.start_issue_date ? { start_issue_date: opts.start_issue_date } : {}),
+            ...(opts.end_issue_date ? { end_issue_date: opts.end_issue_date } : {}),
+            limit: String(opts.limit ?? 20),
+            offset: String(opts.offset ?? 0),
+        });
+        const data = await this.request('GET', `/api/1/deals?${params}`);
+        return data.deals;
+    }
+    /**
+     * List partners (取引先) for a company.
+     * @param opts.company_id  Override company (default: from secrets).
+     */
+    async listPartners(opts = {}) {
+        const params = new URLSearchParams({
+            company_id: String(opts.company_id ?? this.secrets.company_id),
+            limit: String(opts.limit ?? 20),
+            offset: String(opts.offset ?? 0),
+        });
+        const data = await this.request('GET', `/api/1/partners?${params}`);
+        return data.partners;
+    }
+    async listAccountItems(opts = {}) {
+        const params = new URLSearchParams({
+            company_id: String(this.secrets.company_id),
+        });
+        if (opts.limit !== undefined)
+            params.set('limit', String(opts.limit));
+        if (opts.offset !== undefined)
+            params.set('offset', String(opts.offset));
+        const data = await this.request('GET', `/api/1/account_items?${params}`);
+        return data.account_items;
+    }
+    async createPartner(name) {
+        const body = {
+            company_id: this.secrets.company_id,
+            name,
+        };
+        const data = await this.request('POST', '/api/1/partners', body);
+        return data.partner;
+    }
+    async createDeal(input) {
+        const body = {
+            company_id: this.secrets.company_id,
+            issue_date: input.issue_date,
+            type: input.type,
+            details: [
+                {
+                    account_item_id: input.account_item_id,
+                    tax_code: input.tax_code ?? 0,
+                    amount: input.amount,
+                    ...(input.description ? { description: input.description } : {}),
+                },
+            ],
+        };
+        if (input.partner_id)
+            body.partner_id = input.partner_id;
+        if (input.ref_number)
+            body.ref_number = input.ref_number;
+        const data = await this.request('POST', '/api/1/deals', body);
+        return data.deal;
+    }
+    async getWalletTxns(opts = {}) {
+        const params = new URLSearchParams({
+            company_id: String(this.secrets.company_id),
+            ...(opts.walletable_type ? { walletable_type: opts.walletable_type } : {}),
+            ...(opts.start_date ? { start_date: opts.start_date } : {}),
+            ...(opts.end_date ? { end_date: opts.end_date } : {}),
+            limit: String(opts.limit ?? 20),
+            offset: String(opts.offset ?? 0),
+        });
+        const data = await this.request('GET', `/api/1/wallet_txns?${params}`);
+        return data.wallet_txns;
+    }
+    get companyId() {
+        return this.secrets.company_id;
+    }
+    get companyName() {
+        return this.secrets.company_name;
+    }
+}
+//# sourceMappingURL=freee.js.map

package/dist/exclusion/exclusion-checker.d.ts

@@ -0,0 +1,10 @@
+import { Transaction, ExclusionResult } from '../classifier/types.js';
+export declare class ExclusionChecker {
+    private rules;
+    private rulesFile;
+    constructor(rulesFile?: string, dataDir?: string);
+    check(tx: Transaction, employees?: string[]): ExclusionResult;
+    getVersion(): string;
+    getRulesCount(): number;
+}
+//# sourceMappingURL=exclusion-checker.d.ts.map

package/dist/exclusion/exclusion-checker.js

@@ -0,0 +1,162 @@
+// Stage 0 exclusion checker.
+//
+// Reads jp-tax-baseline-v1.json exclusion rules and checks if a transaction
+// should be escalated to human review (= NOT auto-classified).
+//
+// Match types:
+// - regex: pattern match against field
+// - any_keyword: substring list match
+// - any_keyword_or_pattern: keyword + special detector (e.g., transfer_to_employee)
+//
+// Returns excluded:true with rule_id + reason if matched.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { normalizeMemo } from '../classifier/normalize.js';
+import { keywordMatches } from '../classifier/keyword-match.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function defaultDataDir() {
+    const envDir = process.env.COCKPIT_DATA_DIR;
+    if (envDir)
+        return envDir;
+    return path.resolve(__dirname, '../../../../data');
+}
+export class ExclusionChecker {
+    rules;
+    rulesFile;
+    constructor(rulesFile, dataDir) {
+        const dir = dataDir || defaultDataDir();
+        this.rulesFile = rulesFile || path.join(dir, 'exclusion-rules', 'jp-tax-baseline-v1.json');
+        if (!fs.existsSync(this.rulesFile)) {
+            throw new Error(`Exclusion rules not found at ${this.rulesFile}. ` +
+                `Set COCKPIT_DATA_DIR env var or place data files at the expected path.`);
+        }
+        const raw = fs.readFileSync(this.rulesFile, 'utf8');
+        this.rules = JSON.parse(raw);
+        // Sort by priority
+        this.rules.rules.sort((a, b) => a.priority - b.priority);
+    }
+    check(tx, employees) {
+        const memo = tx.memo || '';
+        const normalizedMemo = normalizeMemo(memo);
+        for (const rule of this.rules.rules) {
+            const fieldValue = (() => {
+                switch (rule.match.field) {
+                    case 'memo': return memo;
+                    case 'amount': return String(tx.amount);
+                    case 'partner_name': return tx.partner_name || '';
+                    case 'date': return tx.date;
+                    default: return '';
+                }
+            })();
+            const normalizedField = normalizeMemo(fieldValue);
+            let matchedKeyword;
+            let matched = false;
+            switch (rule.match.type) {
+                case 'regex': {
+                    if (rule.match.pattern) {
+                        try {
+                            const re = new RegExp(rule.match.pattern, rule.match.flags);
+                            if (re.test(fieldValue)) {
+                                matched = true;
+                                matchedKeyword = `regex:${rule.match.pattern}`;
+                            }
+                        }
+                        catch {
+                            // invalid regex, skip
+                        }
+                    }
+                    // Also check alternative_patterns
+                    if (!matched && rule.alternative_patterns) {
+                        for (const alt of rule.alternative_patterns) {
+                            if (keywordMatches(normalizedField, normalizeMemo(alt))) {
+                                matched = true;
+                                matchedKeyword = alt;
+                                break;
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'any_keyword': {
+                    if (rule.match.keywords) {
+                        for (const kw of rule.match.keywords) {
+                            if (keywordMatches(normalizedField, normalizeMemo(kw))) {
+                                matched = true;
+                                matchedKeyword = kw;
+                                break;
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'any_keyword_or_pattern': {
+                    // First check keywords
+                    if (rule.match.keywords) {
+                        for (const kw of rule.match.keywords) {
+                            if (keywordMatches(normalizedField, normalizeMemo(kw))) {
+                                matched = true;
+                                matchedKeyword = kw;
+                                break;
+                            }
+                        }
+                    }
+                    // Then check patterns (= special detectors)
+                    if (!matched && rule.match.patterns) {
+                        for (const pattern of rule.match.patterns) {
+                            if (pattern.type === 'transfer_to_employee' && employees && employees.length > 0) {
+                                // Check if memo contains 振込 + employee name
+                                if (/振込|振替/.test(memo)) {
+                                    for (const emp of employees) {
+                                        if (keywordMatches(normalizedField, normalizeMemo(emp))) {
+                                            matched = true;
+                                            matchedKeyword = `transfer_to_employee:${emp}`;
+                                            break;
+                                        }
+                                    }
+                                    if (matched)
+                                        break;
+                                }
+                            }
+                            // Other pattern types could be added here
+                        }
+                    }
+                    break;
+                }
+                case 'exact': {
+                    if (rule.match.keywords) {
+                        for (const kw of rule.match.keywords) {
+                            if (normalizedField === normalizeMemo(kw)) {
+                                matched = true;
+                                matchedKeyword = kw;
+                                break;
+                            }
+                        }
+                    }
+                    break;
+                }
+            }
+            if (matched) {
+                return {
+                    excluded: true,
+                    rule_id: rule.id,
+                    rule_name_ja: rule.name_ja,
+                    reason: rule.action.reason_template,
+                    suggested_next_step: rule.action.suggested_next_step,
+                    action_type: rule.action.type,
+                    alternative_workflow_id: rule.action.alternative_workflow_id,
+                    matched_keyword: matchedKeyword,
+                };
+            }
+        }
+        return { excluded: false };
+    }
+    getVersion() {
+        return this.rules.version;
+    }
+    getRulesCount() {
+        return this.rules.rules.length;
+    }
+}
+//# sourceMappingURL=exclusion-checker.js.map

package/dist/freee-doctor.d.ts

@@ -0,0 +1,26 @@
+export interface FreeeDoctorReport {
+    ok: boolean;
+    stage?: string;
+    token_source: {
+        env_FREEE_ACCESS_TOKEN: 'set' | 'not set';
+        env_FREEE_COMPANY_ID: string;
+        env_FREEE_TOKEN_EXPIRES_AT: string;
+        secrets_file: string;
+    };
+    token_expires_at?: string;
+    token_expires_at_parseable?: boolean;
+    token_expired_or_near?: boolean;
+    note?: string;
+    configured_company_id?: number | null;
+    live_connection?: boolean;
+    accessible_companies?: Array<{
+        id: number;
+        display_name: string;
+    }>;
+    live_error?: string;
+    verdict?: string | null;
+    action_required?: string | null;
+    error?: string;
+}
+export declare function runFreeeDoctor(): Promise<FreeeDoctorReport>;
+//# sourceMappingURL=freee-doctor.d.ts.map

package/dist/freee-doctor.js

@@ -0,0 +1,82 @@
+// freee connection doctor — one-shot diagnostic for the three freee trip-wires:
+//   ① token source   — FREEE_ACCESS_TOKEN env var vs the secrets file
+//   ② token expiry    — 24h TTL, no auto-refresh
+//   ③ which company_id — the "I have 4-5 test 事業所, which one is live?" problem
+//
+// Reads credentials at runtime; NEVER prints the access token.
+import { loadFreeeSecrets, isTokenExpired } from './secrets.js';
+import { FreeeConnector } from './connectors/freee.js';
+export async function runFreeeDoctor() {
+    const env = process.env;
+    const token_source = {
+        env_FREEE_ACCESS_TOKEN: (env.FREEE_ACCESS_TOKEN ? 'set' : 'not set'),
+        env_FREEE_COMPANY_ID: env.FREEE_COMPANY_ID || 'not set',
+        // An env var here OVERRIDES the file (secrets.ts) — so a stale/malformed value set in the
+        // shell can silently "revive" after you fix the file. Surfaced so that case is diagnosable.
+        env_FREEE_TOKEN_EXPIRES_AT: env.FREEE_TOKEN_EXPIRES_AT || 'not set',
+        secrets_file: '~/.claude/secrets/freee-cockpit-dev.json',
+    };
+    // ① — can we source a token at all? (company_id NOT required here — that's the whole point:
+    //     you must be able to discover the right company_id WITHOUT already having one.)
+    let secrets;
+    try {
+        secrets = loadFreeeSecrets(undefined, { requireCompanyId: false });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            stage: 'token_load',
+            token_source,
+            error: err?.message ?? String(err),
+            action_required: 'No usable access token. Set FREEE_ACCESS_TOKEN (env / plugin settings) or create the secrets file, then re-run.',
+        };
+    }
+    // ② — is the token alive?
+    const expired = isTokenExpired(secrets);
+    const expiresParseable = !!secrets.token_expires_at && !Number.isNaN(new Date(secrets.token_expires_at).getTime());
+    const configured = Number.isFinite(secrets.company_id) ? secrets.company_id : null;
+    const report = {
+        ok: true,
+        token_source,
+        token_expires_at: secrets.token_expires_at || '(not recorded — cannot pre-check expiry)',
+        token_expires_at_parseable: expiresParseable,
+        token_expired_or_near: expired,
+        configured_company_id: configured,
+    };
+    if (secrets.token_expires_at && !expiresParseable) {
+        report.note =
+            'token_expires_at is present but NOT a parseable date (check for stray spaces, e.g. "16: 00: 00"). ' +
+                'A malformed expiry silently defeats the pre-flight expiry check — fix the timestamp or just re-issue the token.';
+    }
+    // ③ — list every accessible 事業所 and validate the configured id against reality.
+    try {
+        const conn = new FreeeConnector(secrets, { skipExpiryCheck: true });
+        const companies = await conn.listCompanies();
+        report.live_connection = true;
+        report.accessible_companies = companies.map((c) => ({ id: c.id, display_name: c.display_name }));
+        if (configured === null) {
+            report.action_required =
+                'No company_id configured. Pick an id from accessible_companies and set FREEE_COMPANY_ID ' +
+                    '(or company_id in the secrets file).';
+        }
+        else if (!companies.some((c) => c.id === configured)) {
+            report.action_required =
+                `Configured company_id ${configured} is NOT accessible by this token — likely a dead/duplicate ` +
+                    `test company. Switch to one of the ids listed in accessible_companies.`;
+        }
+        else {
+            report.verdict = `OK — token is live and company_id ${configured} is valid.`;
+            report.action_required = null;
+        }
+    }
+    catch (err) {
+        report.ok = false;
+        report.live_connection = false;
+        report.live_error = err?.message ?? String(err);
+        report.action_required = expired
+            ? 'Token is expired/near-expiry. Re-issue at https://developer.freee.co.jp/ and update FREEE_ACCESS_TOKEN (or the secrets file).'
+            : 'Could not list companies. If the error is 401, the token is invalid/expired — re-issue at https://developer.freee.co.jp/.';
+    }
+    return report;
+}
+//# sourceMappingURL=freee-doctor.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map